Skip to main content

Errors

A Jaah API call that fails answers with an HTTP status code of 400 or above and, almost always, a JSON body. Read the status code first: it says what kind of failure it was. The body says why. The one exception is an unexpected failure inside Jaah: its 500 body can be plain text (see the table below), so check the response's Content-Type before you parse it.

The error body​

Most error bodies have one field, detail, a sentence written for the person using the console:

{"detail": "This user has already activated their account."}

Show a sentence detail to your user as it is. Do not parse it: its wording can change.

The access check every endpoint runs before its own work answers with a short fixed value instead of a sentence. Map these to your own message:

StatusdetailWhen
401unauthorizedThe call carried no session, or one that has ended.
401session_idle_timeoutYour organization's idle rule ended the session. Other ended sessions answer unauthorized.
403forbiddenYour role, or the permissions on the call, do not allow this endpoint.
404not foundThe item does not exist, or you cannot see it.
404Not FoundJaah serves no such path.

A write on an item you can see but not change answers 403 with a sentence instead, for example {"detail": "You can see this task but not change it — ask for access to it."}.

On any status, detail can instead be an object, usually with a machine-readable code and often a message to show, for example {"detail": {"code": "not_found", "message": "…"}}. A few bodies carry more fields beside detail. Handle a string, a list or an object on every status, not only on 422.

When the request itself does not match what the endpoint declares — a missing field, a wrong type, a value out of range — the status is 422 and detail is a list, one entry per problem. Each entry names where the problem is (loc, for example ["body", "name"] or ["query", "limit"]), says what is wrong (msg) and gives a machine-readable kind (type); an entry may carry more fields:

{
"detail": [
{"loc": ["query", "limit"], "msg": "Input should be less than or equal to 200", "type": "less_than_equal"}
]
}

Each entry also carries the value you sent (input), and ctx where the rule has one. Do not log or show a 422 body as it is when the request held a secret.

Some endpoints check a value themselves and answer 422 with a plain sentence instead. Create playbook and Update playbook answer an invalid playbook with an object holding its issues, one per problem. Each issue names the stage (stage, stage_index) and field it belongs to — null when it belongs to the whole playbook — its severity and a message to show:

{
"detail": {
"issues": [
{"stage": null, "stage_index": null, "field": "name", "severity": "error",
"message": "Another playbook in your organization is already called \"Release\". Choose a different name."}
]
}
}

So a 422 detail, like any other, is a list, a string or an object: handle all three.

The organization-switched refusal​

Every browser tab signed in to the console shares one session, so switching organization in one tab switches them all. To keep a page that still shows the old organization from acting on the new one, send the id of the organization your page shows in an X-Jaah-Org header on each call. When it is no longer your active organization, the call is refused before it runs, with 409 and the organization now active:

{"detail": "org_switched", "active_org": {"id": "7f3c…", "name": "…"}}

Nothing was read or changed. Reload your page into active_org, then retry. A call without the header is never refused this way, and neither is a call from your own script or service: the check applies only to the console's browser session (see Access). The event stream takes the same id as its org query parameter.

Retried writes​

The console may send one write twice, for example when a connection looks dead. It marks each user action with an Idempotency-Key header, so Jaah applies that write at most once and answers every copy with the first copy's answer. A repeated answer carries the header Idempotent-Replayed: true. This applies only to POST, PUT, PATCH and DELETE calls from the console's browser session that carry the header; a call from your own script or service (see Access), one without the header, or one whose body is over 1 MiB is never checked this way: a body over 1 MiB is refused 413 before its key is read. A key is kept for 24 hours.

A key can be refused with one of these detail strings. None of them applied the write again:

StatusdetailWhat it means
400idempotency_key_invalidThe key is not 22 to 64 letters, digits, - or _.
409idempotency_in_progressThe first copy is still running after 25 seconds.
409idempotency_outcome_unknownThe first copy stopped before it answered, so whether it applied is unknown. Reload the item before you act again.
409idempotency_replay_unavailableThe first copy's answer was not kept in full, so it cannot be repeated.
401unauthorizedThe first copy finished, but the console session that sent it has ended, so its answer is not repeated.
422idempotency_key_reusedThe key was used for a different call. Send a new key for each action.

Status codes​

StatusWhat it meansWhat to do
400 Bad RequestThe request is well formed but cannot be done as asked, for example a task or ticket list's pagination cursor the listing did not issue (other cursor lists answer a cursor they did not issue with 422; see Pagination), or a billing call the payment provider refused, with its own sentence in detail.Fix the request; detail says what is wrong.
401 UnauthorizedThe call carried no session, or its session has ended, or the key it carried was refused (see When a key is refused). Every endpoint but the few open ones answers this before anything else.Start a new session in the console, or fix the key, then retry.
402 Payment RequiredThe card was declined while changing your plan or its agent count with Change the plan, or paying with Pay invoice. detail is the payment provider's own sentence. When it gives none, detail is Your card was declined. from Change the plan, or Stripe refused the request. from Pay invoice. The plan does not change and the invoice stays open. Buying a product with a declined card answers 200 with payment.status declined.Use another card, or ask the card's bank.
403 ForbiddenYou may not do this. You may still be able to see the item.Ask an Org Owner or Org Admin for a role that allows it.
404 Not FoundThe item does not exist, or you cannot see it. The two are deliberately not told apart.Check the id; if it is right, ask an Org Owner or Org Admin to grant you a role on it.
409 ConflictThe item is not in a state that allows this, for example a name that is already taken, inviting a user who has already joined, billing that is not connected yet, or a credential sealed with NodeVault, which only your organization's nodes can open. A retried write can also answer 409: see Retried writes.Read detail, change the state, then retry. Jaah never opens a NodeVault credential: give that feature a credential not sealed with NodeVault.
413 Content Too LargeThe request body is over 1 MiB, an uploaded file is bigger than the endpoint accepts, or a Send message text is longer than the Help assistant takes.Send less. Over 1 MiB, detail is Request body too large; an endpoint with its own limit names it in detail.
415 Unsupported Media TypeAn uploaded file is not a type the endpoint accepts, for example a template image in another format.Send a supported type; detail lists them.
422 Unprocessable ContentThe request does not match what the endpoint declares, or a value is invalid. A reused retry key also answers 422: see Retried writes.Fix the fields named in detail.
429 Too Many RequestsYou called an endpoint more often than its limit allows in its time window.See Rate limits for what clears it.
500 Internal Server ErrorSomething failed inside Jaah. The body is JSON with a detail when the endpoint caught the failure itself, for example connection test failed (…) from Test credential; otherwise it is the plain text Internal Server Error, except that a repeated answer to a retried write is {"detail": "Internal Server Error"}. Register agent, and Update agent when fetching the new commit fails, also send an error_id, which their detail repeats.Retry once. If it fails again, create a ticket with the endpoint, the time of the call and any error_id.
502 Bad GatewayA service Jaah relies on for this call, such as Jira, answered with an error, or a node sent a reply Jaah could not read.Retry later. When detail says the tracker refused Jaah's secret, retrying will not help: correct that secret first.
503 Service UnavailableA service Jaah relies on for this call is unavailable.Retry later. Billing endpoints send a Retry-After header with the seconds to wait.
504 Gateway TimeoutA node did not answer in time, or a model call Jaah makes did not complete, for example Send a command to a node, or Retag task.For a node, check it is online; then retry.

A name that is already taken answers 409 with a detail naming what collided, for example {"detail": "A group with this name already exists in this organization."} from Create group or Update group. Choose another name and retry.

A call from a network your organization's IP allowlist leaves out answers 403 with {"detail": "Your organization only allows access from approved networks. Ask an admin to add this address: 203.0.113.7.", "code": "ip_not_allowed", "ip": "203.0.113.7"}. Every call from that address is refused the same way. Show detail; retrying helps only once an org admin adds the address.

A console session that has not yet accepted the Terms of Service answers 403 with {"detail": "Accept the Terms of Service to continue.", "code": "terms_required"} on every call except the ones that read or accept the terms, and the console's own calls that show who you are or end your visit. Retrying helps only once the person accepts them in the console; see Accept the terms.

A NodeVault credential answers 409 with {"detail": "NodeVault credential — not available to Jaah"}, preceded by the name of the feature that tried to use it when there is one. Jaah holds no NodeVault key, so this is the credential's state, not a failure; see How NodeVault works.

Two 503 bodies are common. Billing endpoints answer {"detail": "Billing is temporarily unavailable. Try again in a minute."} with Retry-After: 60 while the payment provider cannot be reached. An endpoint that opens or stores a credential's secret answers {"detail": "the secret-wrapping key is unavailable; try again shortly"} while its encryption key cannot be reached. Get credential seal key answers the secret-wrapping key is unavailable with the cause in parentheses instead.

An endpoint page lists the status codes that endpoint declares. The codes above can come from any endpoint, so not every page lists them all.