Skip to content
ATLAS
 Docs
On this page

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 at https://<atlas-host>/errors/<code>, for example https://<atlas-host>/errors/ERR-0037. Each page explains the cause and the fix.

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://<atlas-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://<atlas-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.
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 in your chain is used up. 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.