> ## Documentation Index
> Fetch the complete documentation index at: https://docs.relace.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Errors
> How the model APIs report failures: status codes, response bodies, and when to retry.
The model APIs convey every failure with a standard HTTP status code. The status is the contract: it tells you whether the request was wrong, your account is blocked, or the model is unavailable. The response body carries a human-readable message, and its shape depends on which endpoint family you called.
## Error bodies
Each endpoint family answers errors in the dialect its clients already parse, including for failures the gateway itself raises (authentication, billing, rate limits, validation).
### Flat JSON
`/v1/code/apply`, `/v2/code/rank`, and `/v1/code/compact` return a single string field.
```json theme={null}
{
"error": "Unsupported model: 'relace-apply-2'"
}
```
### OpenAI error object
`/v1/chat/completions`, `/v1/apply/chat/completions`, and `/v1/search/chat/completions` return the OpenAI error object, so an OpenAI SDK raises its normal typed exception.
```json theme={null}
{
"error": {
"message": "Rate limit exceeded. Retry after the Retry-After interval, or contact support to raise your limits.",
"type": "rate_limit_error",
"param": null,
"code": null
}
}
```
`type` uses OpenAI's vocabulary — `invalid_request_error`, `authentication_error`, `insufficient_quota`, `rate_limit_error`, or `api_error` — and `code` is always `null`.
For third-party models served through `/v1/chat/completions`, an error authored by the upstream provider is passed through with its own status and body, so `type` and `code` may carry that provider's values. Exceptions: a provider `401` or `403` is a credential failure on our side and reaches you as `502`, and a provider `503` or `504` reaches you as a retryable `429`.
### Anthropic error object
`/v1/messages` returns the Anthropic error object, so an Anthropic SDK raises its normal typed exception.
```json theme={null}
{
"type": "error",
"error": {
"type": "rate_limit_error",
"message": "Rate limit exceeded. Retry after the Retry-After interval, or contact support to raise your limits."
}
}
```
`type` uses Anthropic's vocabulary, chosen by status: `400` is `invalid_request_error`, `401` is `authentication_error`, `402` is `billing_error`, `403` is `permission_error`, `404` is `not_found_error`, `413` is `request_too_large`, `429` is `rate_limit_error`, `503` is `overloaded_error`, `504` is `timeout_error`, and other `5xx` are `api_error`. Errors from the model server are rewrapped in this object rather than passed through.
## Status reference
| Status | When | Example message | Retryable |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- | ------------------------------------------------- |
| `400` | Malformed JSON, a field that fails validation, an unknown model, or input past the model's context limit. | `Invalid request body: model: Invalid input: expected string, received undefined` | No — fix the request. |
| `401` | The `Authorization` header (or `x-api-key` on `/v1/messages`) is missing, or the key is not a valid Relace key. Create or check keys at [app.relace.ai](https://app.relace.ai). | `Invalid API key. Check the key, or create one at https://app.relace.ai.` | No |
| `402` | The account is out of credits. Add credits at [app.relace.ai](https://app.relace.ai). | `Out of credits. Add credits at https://app.relace.ai to continue.` | No — retries resume once billing is current. |
| `404` | No such route, or the route is not served on the host you called. | `Route not found: POST /v1/code/rank` | No |
| `405` | Wrong HTTP method. The response carries an `Allow` header. | `Method not allowed; this route accepts POST.` | No |
| `413` | The request body is larger than 32 MiB. | `Request body exceeds the 32 MiB limit.` | No — send less. |
| `429` | Your key exceeded its per-minute request budget, or the model is at capacity. Both carry `Retry-After`. | `Rate limit exceeded. Retry after the Retry-After interval, or contact support to raise your limits.` | Yes — wait for `Retry-After`. |
| `500` | An unexpected failure inside the API. | `Internal server error.` | Retry once. |
| `502` | The model server failed, was unreachable, or returned a response we could not parse. | `Model server error; retry shortly.` | Yes |
| `503` | The model is temporarily unable to serve, or we could not verify your account. Carries `Retry-After`. | `Model 'relace-apply-3' is temporarily unavailable; retry shortly.` | Yes |
| `504` | The model did not respond within the request timeout. | `Request to the model timed out after 60s.` | Yes — consider a smaller input or `stream: true`. |
Messages are meant for humans and logs; branch your code on the status code, not on the message text.
Repos endpoints on `api.relace.run` use their own status vocabulary — see the [Repos documentation](/docs/repos/onboarding).
## Retries and backoff
`429`, `502`, `503`, and `504` are transient: the same request can succeed on a later attempt. `400`, `401`, `402`, `404`, `405`, and `413` will not — retrying them wastes your rate-limit budget. `500` is worth one retry.
When a response carries a `Retry-After` header, wait at least that many seconds before retrying. It is present on rate-limit and capacity `429`s and on `503`s, and it reflects the interval we expect to clear the condition, so honoring it is the fastest path back to a successful call.
Without `Retry-After`, use exponential backoff with jitter — for example 1s, 2s, 4s, 8s, each multiplied by a random factor between 0.5 and 1.5 — and cap the number of attempts. If you need a higher request budget, contact support.