# 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:///errors/`, for example `https:///errors/ERR-0037`. Each page explains the cause and the fix. ## Web app API errors Calls to the ATLAS API return [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457) 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:///errors/`. | | `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:///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](https://docs.atlas.ilionx.dev/reference/budgets.md). | | `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](https://docs.atlas.ilionx.dev/guides/troubleshooting.md). For the requests that produce these errors, see the [Gateway reference](https://docs.atlas.ilionx.dev/reference/gateway.md). ## Related - [Gateway reference](https://docs.atlas.ilionx.dev/reference/gateway.md) - [API keys reference](https://docs.atlas.ilionx.dev/reference/api-keys.md) - [Troubleshooting](https://docs.atlas.ilionx.dev/guides/troubleshooting.md) - [Reference index](https://docs.atlas.ilionx.dev/reference.md)