Developers / Docs / Errors

Errors

ARK answers errors in the shape of the API you called: OpenAI's envelope on /api/v1, Anthropic's on /api/anthropic/v1. The status code tells you what to do next.

Status codes

Status	Meaning	What to do
`400`	The request is invalid: malformed JSON, a wrong type, an unknown parameter, a value out of range, an image that cannot be read. ARK never returns 422.	Fix the request. The message and `param` say what is wrong.
`401`	Missing or invalid API key.	Check the `Authorization: Bearer` header.
`402`	Your credit balance is used up.	Buy credits on the portal.
`403`	The stateful session id belongs to another account.	Use your own session ids.
`404`	Unknown model, or a model of the wrong kind for the endpoint (for example chat with an embedding model).	Use an id from `/api/v1/models`.
`409`	A stateful session conflict: a concurrent request on the same session, the session is full, or `stream` changed.	See Stateful sessions.
`429`	No capacity for this request right now: the model is busy, or the prompt plus `max_tokens` does not fit.	Retry with backoff; if it persists, reduce `max_tokens` or the prompt. See Limits.
`500`	An error on our side.	Retry once; if it repeats, contact support with the `x-request-id`.

OpenAI-style errors

404 on /api/v1/chat/completions

{
  "error": {
    "message": "The model `arklabsai/Qwen3-70B` does not exist or you do not have access to it.",
    "type": "invalid_request_error",
    "param": null,
    "code": "model_not_found"
  }
}

Validation errors name the offending field in param, for example messages[0].content[1].type, and use OpenAI's codes such as missing_required_parameter, unknown_parameter, invalid_type, invalid_value and integer_above_max_value.

Anthropic-style errors

429 on /api/anthropic/v1/messages

{
  "type": "error",
  "error": {
    "type": "rate_limit_error",
    "message": "Maximum number of active inferences for this model has been reached. Please try again later."
  },
  "request_id": "01JABCDXYZ0123456789ABCDEF"
}

Error types: invalid_request_error (400, 409), permission_error (402), not_found_error (404), rate_limit_error (429) and api_error (500). The x-should-retry header says whether a retry can help.

Two exceptions

401 and 403 use a plain body on both APIs: {"detail": "Invalid API Key"}.
409 for a concurrent session request is {"error": "Concurrent requests with the same session id are not allowed. Try again later."}.

Errors in streams

Errors found before the first token come back as a normal error response with the right status. Once a stream has started, the status is already 200: ARK then sends one error event (data: {"error": …} on the OpenAI route, event: error on the Anthropic route) and closes the stream. On the OpenAI route such a stream ends without [DONE].

Retrying

Retry 429 and 500 with exponential backoff and jitter, for example 1, 2, 4 and 8 seconds. ARK sends no Retry-After header. The official SDKs retry these statuses for you (max_retries). Do not retry 400, 401, 402, 403 or 404 without changing the request.

Request ids

Every response, errors included, carries an x-request-id header (and request-id on the Anthropic route). It identifies the request in ARK's logs: include it when you contact support@ark-labs.pl.