NNexithDocs
StatusDashboard ↗
Overview & quickstartModel catalogGuidesAPI referenceIntegrationsOAuth2 / OIDC

Errors and rate limiting

Applies to: all /v1 endpoints


1. Error format#

All non-streaming error response bodies use the following shape:

{
  "error": {
    "message": "The model 'gpt-4o' does not exist.",
    "type": "invalid_request_error",
    "code": "model_not_found"
  }
}
  • message is human-readable and not guaranteed to be stable; do not use it for program logic.
  • code is machine-readable and intended for branching.
  • type is a coarse category (authentication_error / rate_limit_error / billing_error / invalid_request_error / server_error).

2. Error code table#

code HTTP Meaning Suggested handling
missing_api_key 401 No credentials supplied Add Authorization: Bearer
invalid_api_key 401 Key does not exist or has been revoked Use a different key
invalid_token 401 JWT expired or invalid Log in again
unauthorized 401 Other authentication failure Check your credentials
forbidden 403 Not permitted (e.g. calling /v1/images/edits with an nx- key) Use a JWT instead
invalid_request 400 Invalid parameters Correct them according to message
model_not_found 404 Model does not exist or is not exposed Confirm with GET /v1/models
not_found 404 Resource does not exist or does not belong to the current user Check the ID
conflict 409 Uniqueness conflict Query, then retry
payload_too_large 413 Request body/file exceeds the limit Shrink the file (files ≤10MB, global body ≤32MB)
rate_limit_exceeded 429 RPM exceeded Back off according to Retry-After
token_rate_limit_exceeded 429 TPM exceeded Back off according to Retry-After
quota_exceeded 429 Monthly plan quota exhausted Upgrade your plan or wait until next month
insufficient_balance 402 Insufficient balance Top up, then retry
inference_unavailable 502 Upstream unavailable (failover already attempted) Safe to retry
model_overloaded 503 Upstream overloaded Safe to retry
internal_error 500 Server-side exception Retry; if it persists, report the issue

The upstream's real model name, provider URL, and raw error text never appear in responses (opacity is a hard rule); job-related errors return only fixed text.


3. Rate limiting#

Bucketed by (API key, model) in one-minute windows. Resolution order:

  1. Key-level override (set in the console)
  2. Model-level default
  3. Plan default
  4. System fallback: 60 RPM / 40,000 TPM

429 response headers#

Header Description
X-RateLimit-Limit-Requests RPM limit
X-RateLimit-Remaining-Requests Requests remaining this minute (0 when exceeded)
X-RateLimit-Reset Window reset time (Unix seconds)
X-RateLimit-Limit-Tokens TPM limit
X-RateLimit-Remaining-Tokens Tokens remaining this minute (0 when exceeded)
Retry-After Suggested wait in seconds

Client guidance#

import time, random
from openai import OpenAI, RateLimitError

def call_with_retry(fn, attempts=4):
    for i in range(attempts):
        try:
            return fn()
        except RateLimitError as e:
            wait = float(e.response.headers.get("Retry-After", 1))
            time.sleep(wait + random.uniform(0, 0.5))
    raise
  • Only retry 429 / 502 / 503 / 500; retrying 4xx parameter errors is pointless.
  • Exponential backoff with jitter; respect Retry-After.
  • Image jobs are asynchronous: a 202 on submission does not mean generation has completed; when retrying a submission, reuse the idempotency_key.

4. Idempotency#

Endpoint Idempotency key Semantics
/v1/images/generations idempotency_key (optional) The same key from the same user returns the original job
/v1/images/edits idempotency_key (optional) Same as above

Text chat requests have no idempotency guarantee; a network retry creates a new billable request.


Scenario Behavior
Insufficient balance 402 before reaching the upstream; no charge is incurred
Failure midway through a request The full reservation is returned
Job failure/cancellation The full reservation is returned
Disconnect after streaming has started Billed for delivered content; zero delivery is not charged