Docs / Help / Error Codes

Error Codes

API errors are returned as JSON with a standard HTTP status code. The error.message field carries the actionable detail.

#Error response format

{
  "error": {
    "message": "The API key provided is invalid or has been revoked.",
    "type": "authentication_error"
  }
}

#HTTP status codes

#Common errors and fixes

401: invalid API key

Check that the key is passed as a bearer token and has not been deleted in the console:

Authorization: Bearer YOUR_API_KEY

403: quota or permission

Your balance may be too low for the request, or the key lacks access to the requested model. Top up or check the key's model list via GET /v1/models.

404: unknown model or task

The model value or task ID does not exist. Model IDs must match the list returned by GET /v1/models exactly.

429: rate limit exceeded

Reduce your request rate and retry after a delay:

import time, requests

resp = requests.post(url, headers=headers, json=body)
if resp.status_code == 429:
    time.sleep(5)
    resp = requests.post(url, headers=headers, json=body)

5xx: upstream errors

Retry with exponential back-off; most transient provider errors resolve within seconds. Failed requests are not billed:

import time, requests

def post_with_retry(url, headers, body, max_retries=3):
    for attempt in range(max_retries):
        resp = requests.post(url, headers=headers, json=body)
        if resp.status_code < 500:
            return resp
        time.sleep(2 ** attempt)
    return resp