Claude API errors: 401, 429, 500 and interrupted streams

Start by separating configuration errors from access limits and temporary request failures. Change one variable at a time and keep the request ID and timestamp for any failed call.

Reviewed 2026-10-10 · Claude API documentation

A small diagnostic sequence

1. Confirm your key belongs to the intended CAK group and that its plan or prepaid access is active.
2. List models with the same key using GET /v1/models.
3. Send a short message to one returned model ID, using the API starter.
4. If that works, compare the larger failing request with the small one: endpoint, model ID, input size, output limit and requested features.

A model list success checks discovery and authentication. It does not guarantee that a generation request, a long prompt, or a tool call will succeed.

401 and 403: credentials or permission

Check the key’s status, access group and expiry. Use the CAK credential with the CAK host, rather than an Anthropic Console key. Remove accidental whitespace and check whether the client sends an x-api-key header or a bearer token.

Do not log the Authorization or x-api-key header. Repeating a rejected credential without changing its configuration is not a useful retry strategy.

404: endpoint or model

For the Anthropic Messages format, send to https://claudeapikey.dev/v1/messages. Configure Anthropic SDKs with the root base URL. For a Chat Completions client, the usual base is https://claudeapikey.dev/v1.

Check for doubled path segments such as /v1/v1/messages. Re-read the model list with the same key; an ID copied from another provider or an old article may not be available.

429: slow down and reduce parallel work

The current Claude Unlimited group limit is 60 requests per minute. Other account and upstream limits can also produce a 429. Check simultaneous clients, automated retries and the error message rather than assuming every 429 is the same condition.

Use Retry-After when supplied. Otherwise use bounded backoff with a small random delay and a maximum retry count. Stop launching more work while the account is saturated. Never run an unbounded retry loop.

500, 502 and 503: isolate a transient failure

Record the status, request ID if present, model, UTC timestamp and whether the request was streaming. Retry a small, idempotent request after a delay. If the failure repeats, check the service status and contact support with the redacted evidence.

A 500 alone does not tell you whether the fault is in the gateway, upstream provider or a particular request path. Do not claim a root cause without request evidence.

Interrupted stream or partial response

If part of a response already arrived, do not assume nothing ran. A coding agent may already have performed a tool action. Inspect its state before resending work, and avoid silently concatenating a fresh response onto the previous partial output.

Check client and proxy timeouts, then compare a small non-streaming request. The starter keeps automatic generation retries disabled so a connection failure cannot silently multiply requests.

A useful support report

Include the model ID, endpoint path, status, request ID, timestamp, client/version and a minimal redacted reproduction. Exclude API keys, authorization headers, cookies, customer prompts and payment credentials. If a prompt is needed to reproduce the issue, replace private content with a synthetic example.

Claude API is an independent gateway and is not affiliated with or endorsed by Anthropic. Claude and Anthropic are trademarks of their respective owners.