Error codes
This page is for developers who call the Orbit API at https://acme.orbit.inortix.com/api/v1 and want to react to an error. Branch on the code, not on the error text.
{ "error": "Readable message", "code": "validation_error" }error is English text. code is a stable name that stays the same when the wording changes. Some errors add fields, such as position for JQL or limit and used for a quota.
Codes that follow the status
Section titled “Codes that follow the status”When no more specific code applies, an error answers the generic code of its status. The meanings below describe the status in general. Check the specific codes further down first.
| Status | Code | When the status is used |
|---|---|---|
| 400 | bad_request |
Invalid JSON, field data, references, a workflow transition or JQL |
| 401 | authentication_required |
No session, or an expired or revoked one |
| 403 | forbidden |
Not enough membership or role, or a rejected browser origin |
| 404 | not_found |
Missing, or not visible to you |
| 409 | conflict |
Duplicate, stale update, or a resource still in use |
| 422 | unprocessable |
A missing resolution, a failed publication check or a report that is too large |
| 429 | rate_limited |
Too many requests. Read Retry-After and X-RateLimit-*. |
| 503 | unavailable |
A dependency is unreachable |
gone and too_large follow the same rule. validation_error and internal_error keep their meaning.
Sign-in, tokens and access
Section titled “Sign-in, tokens and access”| Status | Code | Cause |
|---|---|---|
| 429 | too_many_failed_sign_ins |
Ten failed sign-ins for one address in 15 minutes. Retry-After gives the end of the window. |
| 401 | invalid_token, token_revoked, token_expired |
The token is unknown, revoked or expired |
| 403 | token_read_only |
A read token tried to write |
| 403 | token_not_allowed |
The route needs site administration, which no token has |
| 403 | session_required |
The route needs a signed-in session, not a token |
| 403 | service_account_inactive |
The service account is suspended or has no owner |
| 403 | product_access_required |
You may not open that product. Ask a site administrator. |
| 403 | site_admin_required, project_admin_required |
The route needs that administrator |
| 409 | too_many_tokens |
More than 25 active tokens |
See API authentication.
Stale versions
Section titled “Stale versions”Writes name the version you read. A change by someone else answers 409.
| Status | Code | Cause |
|---|---|---|
| 409 | issue_version_conflict |
The work item changed since you read it |
| 409 | child_version_conflict |
A comment or work log changed. Send If-Unmodified-Since. |
| 409 | dashboard_changed, view_changed |
Someone saved first. The answer holds the current object. Sending no version answers 428. |
| 409 | goal_version_conflict, board_version_conflict, workflow_version_conflict |
A stale goal, board or workflow |
| 409 | project_key_rename_stale |
Preview the rename again |
| 409 | idempotency_key_reused |
The same Idempotency-Key came with another body |
Limits and quotas
Section titled “Limits and quotas”| Status | Code | Cause |
|---|---|---|
| 409 | quota_exceeded |
A capacity quota was crossed. The body adds quota, limit and used. |
| 429 | too_many_submissions, daily_limit_reached |
A shared form’s per-sender or daily limit. Retry-After is set. |
| 429 | subscription_ran_recently |
A filter subscription ran less than a minute ago |
| 422 | report_scope_too_large |
The report covers more work items than it allows |
The values are in Technical limits.
Search, projects and work
Section titled “Search, projects and work”| Status | Code | Cause |
|---|---|---|
| 400 | invalid_jql |
position and end mark the problem, counted in code points from 0 |
| 400 | invalid_search_consistency, search_languages_invalid |
A value that is not allowed |
| 409 | project_archived, project_in_trash |
A write to an archived or trashed project |
| 409 | project_has_blockers, project_lifecycle_conflict |
The project cannot move to that state now |
| 403 | company_managed_configuration |
Only site administrators change this project’s configuration |
| 409 | team_managed_configuration_is_local |
A team-managed project cannot use a shared workflow |
| 422 | resolution_required, transition_fields_required |
The transition needs a resolution or fields. fieldErrors names them. |
| 409 | transition_requires_approval, transition_selection_required |
An approval or a choice of transition is needed |
| 400 | issue_reason_required |
Archive, restore and security changes need a reason of 3 to 1000 characters |
Forms and imports
Section titled “Forms and imports”| Status | Code | Cause |
|---|---|---|
| 400 | invalid_answer |
An answer was refused. field names the question. |
| 400 | submission_rejected |
The hidden trap field was filled |
| 401 | sign_in_required |
The form accepts signed-in people only |
| 409 | form_paused, form_link_inactive, form_not_shareable |
The form is off, its link is inactive, or it has person questions |
| 400 | invalid_mapping, invalid_jira_export |
A bad CSV mapping, or a file that is not a Jira export |
| 409 | import_not_checked, import_started, import_changed, import_not_running, import_not_runnable, import_finished |
The import is not in a state that allows this step |
Availability
Section titled “Availability”A request answers 503 dependency_unavailable with Retry-After: 5 when the service’s database or session store cannot be reached. Work committed earlier stays. If the connection drops during the commit, the outcome is unknown, so creating requests take an idempotency key. Send the same request again.
Signed incoming webhooks In development
Section titled “Signed incoming webhooks ”A signed request answers 401 webhook_signature_invalid when the signature is missing, malformed or wrong. It answers 401 webhook_signature_expired when the request is more than five minutes off, and 400 webhook_body_invalid for a bad body.
Other products
Section titled “Other products”Pulse errors are { "error": "..." }, with position for query syntax errors. Pulse answers 401 without a session, 403 without access and 404 for an unknown project. It answers 413 for a payload that is too large and 422 for an invalid value. Over a key’s budget it answers 429 with Retry-After. OTLP endpoints answer with a google.rpc.Status body. See OTLP.