Anthropic API errors explained: codes, causes and fixes

Diagnose a Claude API failure from its error type and request identifier. Keep billing, request validation and temporary service pressure separate so the next action addresses the real cause.

Error format at Anthropic

Claude wraps an error type and message in an error object and provides request-identification information. Streaming failures can arrive after a stream has already started. Official documentation.

Read the actual provider response before changing the application. Preserve the error type, message, request identifier and the model that was selected. Record whether the failure occurred before a response, during streaming or while your code interpreted the returned content. Those stages suggest different investigations and should not be collapsed into a generic failure label.

Keep diagnostic information useful without exposing the request’s secrets or customer material. A redacted fixture that reproduces the same error is preferable to a full production conversation. If the error depends on an attachment, create a safe replacement that exercises the same input shape and verify that it still reproduces the condition.

Error code table

Code	Documented type	Investigation	Next action
400	`invalid_request_error`	Request or configured spend constraint	Read the specific message and inspect the request.
401	`authentication_error`	Credential problem	Check the active secret and workspace.
402	`billing_error`	Billing configuration	Inspect the console billing state.
429	`rate_limit_error`	Capacity or applicable spend control	Read retry timing and account controls.
500	`api_error`	Provider-side failure	Retry within a bounded policy.
529	`overloaded_error`	Temporary service pressure	Back off and preserve diagnostics.

Types in the table are from the official error reference; investigation and next-action wording is our guidance. Official documentation.

Use the table to choose an investigation path, not as a reason to rewrite every error into a canned explanation. The provider’s message can contain the field or account condition that makes the difference. Preserve it in a protected diagnostic record and expose only an appropriate application message to the end user.

Do not assume that the first visible status establishes whether retrying is safe or useful. Check the structured type and the context of the request. A rejected billing condition needs an account decision; malformed input needs a request correction; temporary service pressure needs a bounded recovery strategy. A support ticket should make that distinction explicit.

Authentication errors

Recheck the key setup sequence using the environment of the failing process. A local terminal and a deployed worker can have different secret versions.

Reproduce the failure with the smallest Messages request from the same environment. Compare the active secret version, workspace, endpoint and request headers with the known-good configuration. If the developer terminal works but the deployed worker does not, investigate the deployment path rather than immediately creating more keys.

After a replacement key is introduced, verify which processes actually reloaded it. Keep old and new credential identities separate in the operating record without storing their values. If you suspect exposure, follow the account owner’s rotation process and review usage; do not paste the secret into a support message to prove which credential failed.

Rate and quota errors

Inspect organization and workspace limits before increasing retry concurrency. Stop jobs that repeatedly hit an account billing boundary.

Inspect the account controls and the workload’s arrival pattern together. Identify whether a new deployment, restarted queue or parallel evaluation caused a sudden increase in requests. Pause that ramp while collecting evidence. Repeatedly resubmitting the same workload can make the condition harder to diagnose and leave useful work waiting behind retries.

Give queued work an explicit lifetime. When it can no longer meet the application’s purpose, mark it incomplete and surface the reason to the operator. Do not let a paused billing condition turn into an indefinitely growing queue that later floods the account when access resumes. Decide how recovery will be paced before restoring the workload.

Request validation errors

Reduce the failing request to its smallest useful Messages payload. Reintroduce attachments and tool definitions independently so you can identify the field that changes the outcome.

Reduce the request carefully rather than changing many fields at once. Start from the text-only payload that previously worked, then add the system instructions, attachment or tool definition that distinguishes the failing case. Save each meaningful variation and its result. This creates a reproducible explanation of the offending field instead of a series of untraceable prompt edits.

If a field was copied from a different provider’s example, verify that it belongs to the native Messages interface. Similar SDK method names do not guarantee identical schemas. Keep optional features out of the minimal reproduction until the basic request is accepted, then follow the official feature guide when adding them back.

Model and context errors

Verify the exact identifier and supported capabilities against the current model catalog. Keep the response output allowance separate from the input you supply. Official documentation.

Inspect the exact identifier sent by the failing process, not only the display name shown in an application setting. A model configuration can be overridden in a scheduled task or deployment environment. Record the selected value at the application boundary and compare it with the current catalog entry.

For an oversized input, identify which material is necessary for the task before removing content blindly. Preserve the relevant evidence and retest the answer. If you change the model to accept a different request shape, rerun quality checks as well as the request itself. A successful response after changing models is not proof that the original task is still being answered correctly.

Server errors and status

Check the official status link on the Anthropic hub and retain the request identifier. Report a redacted reproduction if an apparently transient problem persists.

Use the AI API cost calculator to turn the model and workload you are considering into an estimate.

Use provider status as one piece of evidence alongside your own failed requests. Record the time window, affected model and the application locations that saw the problem. An apparently healthy status page does not erase a reproducible failure, and an incident notice does not prove every unrelated application bug has the same cause.

When escalating a persistent issue, provide a concise redacted reproduction, request identifiers and the recovery behavior already attempted. State what still fails and what succeeds. This helps a reviewer distinguish a regional application-network problem, a model-specific condition or a request-shape issue without needing access to customer data or credentials.

Last verified 12 Sep 2026 · Source ↗

Frequently asked questions

Should I retry every Claude error?

No. Retry behavior is appropriate for documented transient conditions; fix invalid input or credentials first. Official documentation.

Can streaming fail after it starts?

Yes. Handle the stream’s error events rather than treating its initial connection as completion. Official documentation.

What is a useful minimal reproduction?

A small redacted Messages request, exact model identifier, error type and timestamp.

Should I paste my key into a support request?

No. Include the key’s purpose or non-secret identifier only when the support channel requests it.

Where should I check model spelling?

Use the direct Claude API identifier in the official catalog. Official documentation.

Sources

Last verified 12 Sep 2026 · Source ↗