Errors

When a request fails, the API responds with an HTTP error status and a JSON body that describes the error:

Error response

{
  "error": {
    "code": 401,
    "message": "The API key you provided is invalid."
  }
}

code is the same as the HTTP status, and message explains the error. Some errors also have a metadata object with more detail.

Status Codes

Status	Meaning	Retry?
400	The request is invalid. For example, the body isn't valid JSON, a required parameter is missing, the model id doesn't exist, or there are too many images.	No
401	The API key is missing or invalid.	No
402	The organization's balance is too low for the request.	No
403	The API key isn't allowed to make this request.	No
408	The request took too long.	Yes
429	The organization sent too many requests. See Rate limits.	Yes
500	Tuna had an internal error. It is usually temporary.	Yes
502	The model failed or returned an invalid reply.	Yes
503	Tuna doesn't have capacity for this model right now. Try again shortly, or use another model.	Yes

See Retries for how long to wait before trying again.

400: Invalid Request

The message says what is wrong. Fix the request before sending it again, since the same request will fail the same way. If the model id is the problem, get a current id from the models list.

401: Authentication

Message	Cause
You must provide an API key.	The request has no `Authorization` header.
The API key you provided is invalid.	The key is malformed or does not exist.

Check that the request sends Authorization: Bearer tuna_yourApiKeyHereWithTunaUnderscore, and that the key was copied in full. See Authentication.

402: Balance

The message is "The account linked with the API key has reached its spending limit/run out of credits."

The organization's balance is checked before a request runs, using an estimate of the request's size. If the balance is too low, the request fails with 402 before any tokens are charged. Add credit to fix it. See Billing.

429, 500, 502, and 503: Temporary Errors

These errors usually go away on their own. Wait and retry, and follow the Retry-After header when a response has one. The OpenAI SDKs and the Vercel AI SDK retry them for you. See Retries.

Errors During a Stream

If a stream fails after it has started, the HTTP status is already 200. The error comes as a last chunk with an error field and a finish_reason of error. See Errors during a stream.

Handling Errors in Code

The OpenAI SDKs turn error responses into exceptions that carry the status and message:

try {
  const response = await client.chat.completions.create({
    model: "tuna-us/example-lab/example-model-id",
    messages,
  });
} catch (error) {
  if (!(error instanceof OpenAI.APIError)) throw error;
  console.error(error.status, error.message);
}

import openai

try:
    response = client.chat.completions.create(
        model="tuna-us/example-lab/example-model-id",
        messages=messages,
    )
except openai.APIStatusError as error:
    print(error.status_code, error.message)
except openai.APIConnectionError:
    print("Could not reach Tuna")

By the time your code sees a 429 or 5xx error, the SDK has already retried it, twice by default. See Retries.