Errors

Claud uses conventional HTTP status codes and returns a consistent JSON envelope for every error, on every endpoint.

The error envelope#

{
  "error": {
    "message": "The model 'claud-ultra' does not exist or you do not have access to it.",
    "type": "invalid_request_error",
    "code": "model_not_found",
    "param": "model",
    "request_id": "req_01J9X3Q5K7M2N8P4R6T0V2W4Y6"
  }
}

messagestring

A human-readable description. Safe to log; never contains secrets.

typestring

The error family (see below). Use it for coarse handling such as "retry" versus "fix the request".

codestring

A stable machine-readable code. Branch on this, not on message.

paramstring

Present when the error relates to a specific request field, for example messages or model.

request_idstring

Identifies the request in Claud's logs. Include it when contacting support. Also returned in the x-request-id header on every response.

For 429 and some 503 errors a retry-after header tells you how many seconds to wait.

Anthropic-format endpoints#

Errors raised by POST /v1/messages follow the Messages API convention so the Anthropic SDKs surface them correctly. The code and request_id fields are the same as above:

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "max_tokens: Invalid input: expected number, received undefined",
    "code": "invalid_request",
    "request_id": "req_01J9X3Q5K7M2N8P4R6T0V2W4Y6"
  }
}

Authentication failures on that endpoint use the standard envelope shown first; both SDK families read error.message from it.

Error types#

Error codes#

Request validation (400)#

Authentication (401)#

Permission (403)#

Models (404)#

Balance (402)#

Rate limits and caps (429)#

See Rate limits for the numbers per plan and the headers to watch.

Upstream and platform (5xx)#

Errors during a stream#

If a stream has already started when something fails, the HTTP status is already 200. Claud then sends an error event on the stream, followed by data: [DONE]:

data: {"error":{"message":"The model provider timed out.","type":"provider_error","code":"provider_timeout","request_id":"req_..."}}

data: [DONE]

Any tokens generated before the failure are billed; the reservation for the rest is released. See Streaming.

Handling errors well#

import OpenAI, { APIError, RateLimitError } from 'openai';

const client = new OpenAI({ apiKey: process.env.CLAUD_API_KEY, baseURL: 'https://api.claudkey.com/v1', maxRetries: 3 });

try {
  const res = await client.chat.completions.create({ model: 'claud-5.1', messages });
} catch (err) {
  if (err instanceof RateLimitError) {
    // The SDK already retried with back-off; surface a friendly message.
  } else if (err instanceof APIError) {
    const code = err.error?.error?.code ?? err.code;
    if (code === 'insufficient_balance') notifyBillingOwner();
    else if (code === 'context_length_exceeded') truncateHistoryAndRetry();
    else console.error(`Claud error ${code} (request ${err.headers?.['x-request-id']})`);
  } else {
    throw err;
  }
}

• Retry 429, 502, 503 and 504 with exponential back-off and jitter, respecting retry-after. The OpenAI SDKs do this by default.
• Do not retry 400, 401, 402, 403 or 404; the same request will fail again.
• Log request_id on every failure. It lets support trace the exact request across the gateway, the ledger and the provider.