type. Your code uses them to tell a request to fix from one to retry. The status table lists the codes NagaAI returns and whether a retry can help.
Error body
Chat Completions, Responses and every non-chat endpoint return the OpenAI shape:/v1/messages returns the Anthropic shape:
message is text for people, and NagaAI can change it. Decide in code by the HTTP status first, then by error.type or error.code. code and param are missing or null on many errors. On /v1/messages, error.type uses Anthropic’s names by status, such as authentication_error, billing_error and rate_limit_error, and there is no code.
Every response from an API endpoint, error or not, carries an x-request-id header. Include it when you contact support.
Error sources
Your request
NagaAI checks the request before it picks a provider. A missing field, a wrong type or an image sent to a text-only model fails here with400 and a message such as body.messages.0.content: .... Fix the request and send it again.
A provider that couldn’t serve it
On a timeout, a5xx, a rate limit or another provider-side failure, NagaAI moves the request to the next provider, up to three attempts. If every attempt fails you get 503 with a generic message, and NagaAI does not charge the request.
A provider that accepts the request and then sends nothing counts as a timeout. On /v1/responses, /v1/chat/completions and /v1/messages, NagaAI waits at most 90 seconds from receiving the request for a provider to start answering. The limit holds on every attempt, the last one included. Past it you get the same 503, so a client with a two-minute timeout gets an error instead of hanging. Once the answer has started, NagaAI doesn’t cut a long generation.
A provider’s content filter
A content filter belongs to one provider. NagaAI sends a request that one provider filtered to another provider of the model, at no charge, for every model kind. If a second provider filters it too, or the model has a single provider, you get400. The message is Request rejected by upstream content moderation. and, in the OpenAI formats, code: "content_moderation". Change the content, or try another model. A video job a provider filters after it accepted the job fails with error.type: "moderation", since the provider already holds the job.
A provider that rejected a request NagaAI accepted
You get400 with the provider’s text after Upstream returned an error: . This is a bug in NagaAI’s conversion, not in your request. Report it with the x-request-id.
Status codes
Each status NagaAI returns, with itstype or code and whether a retry can help:
Retry-After holds seconds. It comes with 429 and with some 503 responses.
Errors in a stream
NagaAI holds back the HTTP status until the first piece of content is ready. If every provider fails before that point, you get a normal error response with one of the status codes listed under Status codes. After content has started, the status is already200, so an error arrives inside the stream. Each format sends it its own way:
A retry costs only the new request, because a stream that fails midway isn’t charged, see Billing.
Retry failed requests
Retry only the statuses that a second attempt can fix, and wait forRetry-After when the response has it:
408, 409, 429 and 5xx twice by default and read Retry-After. Raise max_retries (Python) or maxRetries (Node.js) instead of writing a loop, unless you need custom backoff.
A request your client gave up on can still finish at NagaAI and be charged. Retrying it after a client timeout can charge twice, so set the client timeout above your longest expected answer.