Errors

Error shape

Chat Completions, Responses and every non-chat endpoint return the OpenAI shape:

{"error": {"type": "invalid_request_error", "message": "body.messages: ...", "code": null, "param": null}}

/v1/messages returns the Anthropic shape:

{"type": "error", "error": {"type": "invalid_request_error", "message": "..."}}

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.

Where an error comes from

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 with 400 and a message such as body.messages.0.content: .... Fix the request and send it again. A provider that could not serve it. On a timeout, a 5xx, a rate limit or an exhausted provider quota, NagaAI moves the request to another 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’s content filter. You get 400 with the message Request rejected by upstream content moderation. and, in the OpenAI formats, code: "content_moderation". Change the content, or try another model. A provider that rejected a request NagaAI accepted. You get 400 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

Status	`type` or `code`	Meaning	Retry
`400`	`invalid_request_error`	The request failed validation	No, fix it
`400`	`unsupported_modality`	The model does not accept this input type, see `architecture.input_modalities`	No
`400`	`model_not_found`	No model has this id or alias, or it does not serve this endpoint	No
`400`	`content_moderation`	A provider’s content filter rejected the request	No
`401`	`invalid_api_key` and others	Missing or wrong key, see Authentication	No
`402`	`insufficient_quota`	The balance is too low for a paid model	After a top-up
`403`	`credit_limit_exceeded`	The key reached its own spending limit	After raising the limit
`403`	`inappropriate_content`	NagaAI’s moderation blocked an image prompt	No
`404`		The path does not exist. For an unknown path the body is plain text, not JSON	No
`405`		The path exists but not with this HTTP method	No
`408`		The request body stopped arriving for 60 seconds, or took longer than 15 minutes	Once
`410`	`model_deprecated`	The model was retired	No, switch models
`413`		The body is over 32 MiB, or one inline part of a chat request is over 20 MiB	No
`422`	`billing_metering_incomplete`	The model has no price for an input or output in the request, such as audio, so NagaAI did not serve it	No, change the model or the input
`429`	`rate_limit_exceeded`	The free-model rate limit, see Limits	After `Retry-After`
`500`	`server_error`	A bug in NagaAI	Once, then report
`503`	`server_error`	No provider could take the request right now, or NagaAI is shedding load	After `Retry-After`, or with backoff

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 already 200, so an error arrives inside the stream:

Endpoint	What the stream sends
Chat Completions	`data: {"error": {...}}`, then `data: [DONE]`
Responses	An `error` event with `code`, `message` and `param`, then `response.failed`
Messages	`event: error` with the Anthropic error shape, then the connection closes

NagaAI does not charge a stream that fails midway, so a retry costs only the new request.

Retry pattern

import random
import time

import openai

RETRYABLE = {408, 429, 500, 503}

def create_with_retry(client, **kwargs):
    for attempt in range(5):
        try:
            return client.chat.completions.create(**kwargs)
        except openai.APIStatusError as error:
            if error.status_code not in RETRYABLE or attempt == 4:
                raise
            wait = error.response.headers.get("retry-after")
            time.sleep(float(wait) if wait else 2**attempt + random.random())

import OpenAI from "openai";

const RETRYABLE = new Set([408, 429, 500, 503]);

async function createWithRetry(client, params) {
  for (let attempt = 0; ; attempt++) {
    try {
      return await client.chat.completions.create(params);
    } catch (error) {
      if (!(error instanceof OpenAI.APIError) || !RETRYABLE.has(error.status) || attempt === 4) throw error;
      const wait = Number(error.headers?.get("retry-after")) || 2 ** attempt + Math.random();
      await new Promise((resolve) => setTimeout(resolve, wait * 1000));
    }
  }
}

The OpenAI and Anthropic SDKs already retry 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.

Get started

How NagaAI works

Features

API guides

Account

Product

Error shape

Where an error comes from

Status codes

Errors in a stream

Retry pattern

​Error shape

​Where an error comes from

​Status codes

​Errors in a stream

​Retry pattern

Error shape

Where an error comes from

Status codes

Errors in a stream

Retry pattern