Errors

Claudech 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 Claudech'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)#

Common error messages#

"Provider returned error"#

Many AI API services show this text when the model behind them fails. On Claudech the same situation returns 502 with the code provider_error and the message "The upstream model provider returned an error." These requests are not billed. Retry with back-off; if one model keeps failing, try another model and send support the request_id.

"Invalid beta flag"#

Anthropic-format clients such as Claude Code and the Anthropic SDKs can send an anthropic-beta header that turns on experimental features. Endpoints that do not recognise a flag reject the request with "invalid beta flag". Claudech's POST /v1/messages accepts the header and ignores it, so this error does not come from Claudech. If you see it, the client is still sending requests somewhere else: in Claude Code, check that ANTHROPIC_BASE_URL is exactly https://api.claudech.com (Claude Code setup).

"Rate limit reached"#

A 429 with rate_limit_exceeded, tokens_per_minute_exceeded or concurrency_limit_exceeded. Wait for the number of seconds in retry-after and send the request again. The limits for each plan are on Rate limits.

"Insufficient balance"#

A 402 with insufficient_balance: the balance cannot cover the worst-case cost of the request. Top up under Billing; retrying without topping up fails the same way.

Errors during a stream#

If a stream has already started when something fails, the HTTP status is already 200. Claudech 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.CLAUDECH_API_KEY, baseURL: 'https://api.claudech.com/v1', maxRetries: 3 });

try {
  const res = await client.chat.completions.create({ model: 'claude-opus-5-5', 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(`Claudech 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.