Errors & Status Codes

Error shapes, status codes and retry guidance.

Errors use the OpenAI error shape, so SDK exception classes work as expected.

Error shape

{
  "error": {
    "message": "Human-readable description",
    "type": "error_type",
    "code": "optional_code"
  }
}

Status codes

Status	Type	Meaning	What to do
`400`	invalid_request_error	Malformed body or bad parameter.	Fix the request; don't retry.
`401`	authentication_error	Missing, invalid, revoked or expired key.	Check the Authorization header.
`402`	insufficient_quota	Balance is empty or the key hit its credit limit.	Add credits or raise the key's limit.
`403`	permission_error	Model or IP not allowed for this key.	Update the key's model or IP settings.
`404`	invalid_request_error	Unknown model ID.	Check `/v1/models`.
`429`	rate_limit_error	Too many requests for this key.	Back off and retry.
`500` / `502`	upstream_error	Model provider failed or timed out.	Retry with backoff.

Examples

401 Unauthorized

{
  "error": {
    "message": "Invalid API key",
    "type": "authentication_error",
    "code": null
  }
}

402 Insufficient credits

{
  "error": {
    "message": "Insufficient credits. Add credits in your dashboard.",
    "type": "insufficient_quota",
    "code": "insufficient_quota"
  }
}

403 Model not allowed

{
  "error": {
    "message": "This API key is not allowed to use openai/o1",
    "type": "permission_error",
    "code": null
  }
}

404 Unknown model

{
  "error": {
    "message": "Model 'openai/gpt-5-ultra' not found",
    "type": "invalid_request_error",
    "code": "model_not_found"
  }
}

429 Rate limited

{
  "error": {
    "message": "Rate limit exceeded. Retry after a short delay.",
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded"
  }
}

500 Upstream timeout

{
  "error": {
    "message": "Upstream provider timed out",
    "type": "upstream_error",
    "code": null
  }
}

Retrying

Retry 429 and 5xx with exponential backoff and jitter. The official SDKs retry twice by default; raise it with max_retries:

Python

import os
from openai import OpenAI

client = OpenAI(base_url="https://api.000labs.xyz/v1", api_key=os.environ.get("000_LABS_API_KEY"), max_retries=5)

Streaming Usage & Limits