Errors#

Look up the error formats that ATLAS returns for web app API calls and gateway calls, and what the common codes mean.

Look up any ERR-nnnn code in the error catalogue. Each code has its own page that explains the cause and the fix, for example ERR-0037.

Web app API errors#

Calls to the ATLAS API return RFC 9457 Problem Details with the content type application/problem+json. Send Accept: application/problem+json or Accept: */*.

Field	Meaning
`type`	Address of the catalogue page for this error, `https://<docs-host>/errors/<errorCode>`.
`title`, `status`, `detail`, `instance`	The standard Problem Details members. `detail` says what to change.
`errorCode`	A stable code such as `ERR-0037`, or a general code such as `VALIDATION_ERROR` or `NOT_FOUND`.
`traceId`, `spanId`	Present when the request was traced. Give them to your ilionx contact.
`errors[]`	For validation failures, one `{field, code}` entry per rejected field.
`rejectedField`, `sortableFields`	On a rejected sort (`INVALID_SORT`): the field you sent and the fields you may sort by.

ATLAS never returns stack traces or internal messages. An unexpected failure returns 500 with a generic message. Report the traceId to your ilionx contact.

json

{
  "type": "https://<docs-host>/errors/ERR-0037",
  "title": "API key name already exists",
  "status": 409,
  "detail": "An API key with this name already exists among your keys.",
  "errorCode": "ERR-0037"
}

ERR-0037 means you already own a personal key with that name, whichever space it acts under. A duplicate project key name returns ERR-0086, because project key names are unique per project.

Gateway errors#

The gateway answers in the format of the API you called. Addresses under /gateway/anthropic use the Anthropic format. Every other gateway address uses the OpenAI format.

Item	OpenAI-compatible clients	Anthropic-compatible clients
Body	`{"error":{"message","type","param","code"}}`	`{"type":"error","error":{"type","message"},"request_id"}`
Gateway code	`error.code`, for example `budget_exceeded`	Not present. Use `error.type` and the message
HTTP status	The status for the code	The status for the code, except `billing_error` is `402`, `overloaded_error` is `529` and `api_error` is `500`
Stream errors	A final JSON error frame, then the stream ends	A final `event: error` frame with the same envelope
`401` extras	`WWW-Authenticate: Bearer realm="ATLAS Gateway"`	None

Rate limits and availability errors include a Retry-After header when the provider sent one. Wait that long before you retry.
Every gateway response carries an atlas-request-id header, also in error bodies. Anthropic-compatible responses add request-id with the same value. Give it to your ilionx contact.
A 401 is the same for every cause, so a wrong, expired or revoked key cannot be told apart.

Error types#

The type field tells a client how to react.

Meaning	OpenAI `type`	Anthropic `type`
Missing or invalid key	`authentication_error`	`authentication_error`
Not allowed	`permission_error`	`permission_error`
Unknown model or resource	`invalid_request_error`	`not_found_error`
Invalid request	`invalid_request_error`	`invalid_request_error`
Budget used up	`quota_error`	`billing_error`
Request body too large	`invalid_request_error`	`request_too_large`
Throttled	`rate_limit_error`	`rate_limit_error`
Provider timed out	`server_error`	`timeout_error`
Provider overloaded or unavailable	`server_error`	`overloaded_error`
Provider or gateway failure	`server_error`	`api_error`

Common gateway codes#

Code	HTTP	What it means
`authentication_required`	`401`	The key is missing, invalid, expired or revoked.
`no_acting_context`	`403`	A personal key is not bound to a Team space or an active project.
`organization_suspended`	`403`	Your organisation is suspended or scheduled for deletion.
`project_archived`	`403`	The project the key acts under is archived.
`provider_disabled`, `provider_access_denied`	`403`	The model's provider is disabled or refused the credentials.
`model_not_found`, `project_has_no_models`	`404`	The model name is wrong, inactive or not offered to your space or project.
`provider_resource_not_found`	`404`	The provider answered that the requested resource does not exist.
`model_not_supported_for_endpoint`, `invalid_request`	`400`	The request is invalid or the model cannot serve that endpoint.
`request_too_large`	`413`	The request body is over 25 MB.
`budget_exceeded`	`429` (`402` for Anthropic-compatible clients)	A budget, funding or per-member daily or weekly limit is used up. The message names the window, limit and reset time. See Budgets.
`provider_rate_limited`	`429`	The provider is throttling requests.
`provider_unavailable`, `upstream_overloaded`	`503` (`529` for Anthropic-compatible clients)	The provider is overloaded or unavailable. Retry after a short wait.
`provider_error`, `provider_incompatible`, `connection_error`, `empty_response`, `provider_stream_interrupted`	`502`	The provider failed or answered unexpectedly.
`upstream_timeout`	`504`	The provider did not answer in time.
`gateway_internal_error`, `serialization_error`	`500`	The gateway failed internally. Give the request id to your ilionx contact.

To work through a failure step by step, use Troubleshooting. For the requests that produce these errors, see the Gateway reference.

Bug reporting errors#

These codes come from the web app's Report a bug dialog. See Report a bug.

Code	HTTP	What it means
`ERR-0142`	`503`	Bug reporting isn't enabled for this ATLAS. Ask your Admin or your ilionx contact.
`ERR-0143`	`503`	The issue tracker is unavailable, so the report wasn't delivered. Try again shortly.
`ERR-0144`	`413`	The report is over 64,000 characters in total. Shorten the description or steps and send it again.

Sending more than 5 reports in an hour returns 429 with a Retry-After header.

Organisation deletion errors#

These codes come from scheduling, undoing or completing an organisation deletion. Only platform administrators see them.

Code	HTTP	What it means
`ERR-0145`	`409`	Deletion of this organisation is already scheduled. Refresh to see the date.
`ERR-0146`	`409`	This organisation has no scheduled deletion to undo.
`ERR-0147`	`409`	The due date has passed, so the deletion can no longer be undone.
`ERR-0148`	`409`	This change is blocked while the organisation is pending deletion. Undo the deletion first.
`ERR-0149`	`409`	Only a deleted organisation whose cleanup has failed can be retried. Refresh to see its status.