Errors and Debugging

When a request fails before the model starts answering, the API returns a non-2xx HTTP status with a JSON body. The body is in the shape of the library the route speaks: the OpenAI shape on every route but two, the Anthropic shape on /v1/messages and the Responses shape on /v1/responses. The status, the message and the one-word error_type are the same in all three.

Error format#

{
  "error": {
    "code": 402,
    "message": "This API key has reached its monthly limit of 2,000.00 DA.",
    "metadata": {
      "limit_source": "key",
      "error_type": "payment_required"
    }
  }
}

metadata carries whatever detail applies: the limit that stopped a 402 (limit_source), the fields that failed validation on a 400 (errors), the kinds of personal data a filter found on a 403 (types), the provider's own code on a refusal from the model (provider_code).

const res = await fetch("https://opendunes.com/v1/chat/completions", { /* … */ });
if (!res.ok) {
  const { error } = await res.json();
  console.error(error.code, error.metadata.error_type, error.message);
}

Anthropic shape — /v1/messages#

An error on /v1/messages is the object the Anthropic libraries read:

{
  "type": "error",
  "error": {
    "type": "billing_error",
    "message": "Insufficient balance for this request.",
    "error_type": "payment_required"
  },
  "request_id": null,
  "metadata": {
    "limit_source": "wallet"
  }
}

Responses shape — /v1/responses#

An error on /v1/responses is a failed response, the object the OpenAI library's responses.create reads:

{
  "id": "resp_a2d1a1edd30c48a4823171d3aa1e1b78",
  "status": "failed",
  "error": {
    "code": "server_error",
    "message": "Invalid API key."
  },
  "error_type": "authentication"
}

In both shapes the HTTP status is the one in the tables below. Read the status from the response, not from the body.

Status codes#

The request:

You, the caller:

The model:

Retry-After header#

A 429 and a 503 carry a Retry-After header: the number of seconds to wait before retrying. A 429 also carries the provider's X-RateLimit-* headers when it sent them. No successful answer carries either.

HTTP/1.1 429 Too Many Requests
Retry-After: 12
Content-Type: application/json

{"error":{"code":429,"message":"Rate limit exceeded.","metadata":{"error_type":"rate_limit_exceeded"}}}

The OpenAI and Anthropic libraries already honour Retry-After on the statuses they retry. With fetch, read the header and wait before retrying. A 402 is never a wait-and-retry case.

Payment required#

A 402 names the limit that stopped it in metadata.limit_source:

A request admitted while your balance is above zero settles in full, even past zero or past a cap.

Guardrail and filter errors#

A request a guardrail blocks answers 403 before it reaches a model, and nothing is charged. When the sensitive-information filter blocks it, metadata.types lists what it found:

{
  "error": {
    "code": 403,
    "message": "Personal information detected in prompt. Please remove PII before sending.",
    "metadata": {
      "types": ["email"],
      "error_type": "permission_denied"
    }
  }
}

Errors from the model#

When the provider refuses or fails, you get its status and its message, with its own error code in metadata.provider_code where it gave one. A 500 is the exception: its message is always generic and nothing of the cause is passed on.

Errors during streaming#

An error before the stream opens — a bad key, an empty wallet, an unknown model, a provider that fails before its first word — arrives as an ordinary error response, with its status and the route's shape above.

Once the answer has begun, its 200 is already sent. An error after that point arrives inside the answer:

• Streamed, the last event carries error and finish_reason: "error", then [DONE]:

  Text

  Copy

  data: {"object":"chat.completion.chunk","error":{"code":502,"message":"The model is down, or answered with nothing usable.","metadata":{"error_type":"provider_unavailable"}},"choices":[{"index":0,"delta":{"content":""},"finish_reason":"error"}]}
  
  data: [DONE]

• Not streamed, the body carries error and no choices.

See Streaming for the event format.

Error types#

metadata.error_type names the cause in one word, the same word on every route:

A provider that names a more precise type keeps its own word.

Debugging with X-Request-Id#

Every response — success or error — carries an X-Request-Id header:

X-Request-Id: a2d19592-a8d5-49f6-94be-4ed27498a8aa

Include it when you contact support. A model answer also carries X-Generation-Id, the handle of its receipt.