Overview

Chat Completions errors generally use {"error":{"message":"..."}}. Messages uses an Anthropic error envelope with type, error and request_id; see Messages API. Error details can vary, so do not assume every error has identical fields. Read the status, a safely logged message, X-Request-Id, and Retry-After where present.

Status	Likely cause	Next step
400	Invalid JSON, missing fields, query parameters, unsupported model capability	Send a minimal valid body and add optional fields one at a time.
401	Missing, invalid, expired, or revoked Netra key	Check the connection secret and key status in the correct organization.
402	Insufficient available credit or a key/organization spending limit	Check balance, reservations, and budget; repeated immediate retries will not fix it.
404	Unknown endpoint or unavailable model	Verify the base URL and exact model ID with the same key.
405	Wrong HTTP method	Use GET for models and POST for generation.
409	Duplicate claimed X-Request-Id	Investigate the original execution; the conflicting request did not start another inference.
413	Body exceeds the request limit	Reduce the body. The default limit is 64 MiB; model-specific limits can be lower.
415	Compressed request body	Send uncompressed JSON.
429	Rate limit, token limit, or model capacity	Honor Retry-After; reduce concurrency and retry with bounded backoff.
502, 503	Generation service temporarily unavailable	Retry with bounded backoff after checking whether the original execution completed.
504	Generation timed out	Honor Retry-After if supplied; allow suitable timeout for the model.
Other error status	Request rejected or generation failed	Inspect its safe error detail and model capability requirements.

There is no universal requests-per-minute or tokens-per-minute allowance in these docs: configured key, organization, and model limits govern your traffic. Retry-After values are seconds when supplied by the API.

A request must fit the model's byte and context-token limits. Check the safe error detail before retrying.

Request IDs and retries

The optional X-Request-Id header accepts a UUID. Generate one UUID for an intended execution, retain it with your application logs, and reuse that ID if retrying the same execution. Do not hard-code the same ID for unrelated calls.

Duplicate-request detection is best-effort and time-limited. A repeated ID can return 409, but it does not guarantee exactly-once execution, replay the original response, or make all retries free. After a transport failure, a retry may start another generation.

After an ambiguous timeout, inspect Observe or the observation MCP for the original request before issuing a new ID. Use exponential backoff with jitter, a retry limit, and an overall deadline for transient failures. Check your SDK's retry settings so they do not multiply application-level retries. Do not retry validation, authentication, or budget failures without fixing their cause.