Errors

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 and /v1/code/compact return a single string field.

{
  "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.

{
  "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.

{
  "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.	`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.	`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/edit`	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.

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 429s and on 503s, 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.

General

Relace Models

Open Models

Repos

Error bodies

Flat JSON

OpenAI error object

Anthropic error object

Status reference

Retries and backoff

​Error bodies

​Flat JSON

​OpenAI error object

​Anthropic error object

​Status reference

​Retries and backoff

Error bodies

Flat JSON

OpenAI error object

Anthropic error object

Status reference

Retries and backoff