Error Handling

Error response format

Errors return a JSON body with an error object and an appropriate HTTP status:

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

The type field is the machine-readable discriminator. Common values:

`type`	When
`authentication_error`	Missing or invalid API key (401).
`invalid_request_error`	Malformed body or an unsupported parameter (400).
`model_not_found`	The `model` id is not available (400).
`not_found_error`	The model exists but no provider can serve it under the request’s routing constraints, for example `provider: {"zdr": true}` (404).
`upstream_error`	The upstream provider is unavailable (502).

Status codes

Status	Meaning
400	Bad request (invalid parameters or unknown model)
401	Unauthorized (missing or invalid API key)
403	Forbidden (for example, insufficient credits)
404	No provider can serve the model under the request’s routing constraints
429	Rate limit exceeded
500	Server error
502	Upstream provider unavailable
503	Service temporarily unavailable

Handle errors with the SDK

OpenAI client libraries map these statuses to typed exceptions:

Python

import os, time
from openai import OpenAI, AuthenticationError, RateLimitError, APIError

client = OpenAI(base_url="https://api.redpill.ai/v1", api_key=os.environ["API_KEY"])

try:
    resp = client.chat.completions.create(
        model="openai/gpt-5",
        messages=[{"role": "user", "content": "Hello"}],
    )
except AuthenticationError:
    print("Invalid API key")
except RateLimitError:
    print("Rate limited; back off and retry")
except APIError as e:
    print(f"API error {e.status_code}: {e.message}")

JavaScript

try {
  const resp = await client.chat.completions.create({
    model: "openai/gpt-5",
    messages: [{ role: "user", content: "Hello" }],
  });
} catch (error) {
  if (error.status === 401) console.error("Invalid API key");
  else if (error.status === 429) console.error("Rate limited");
  else console.error("API error:", error.message);
}

Retry transient errors

Retry 429 and 5xx responses with exponential backoff. Do not retry 400 or 401: they will fail again until you fix the request or the key.

import time
from openai import RateLimitError, APIError

def with_retry(call, max_retries=3):
    for attempt in range(max_retries):
        try:
            return call()
        except (RateLimitError, APIError) as e:
            status = getattr(e, "status_code", 500)
            if status in (429, 500, 502, 503) and attempt < max_retries - 1:
                time.sleep(2 ** attempt)
            else:
                raise

Common cases

Invalid API key (401, authentication_error)

Check the key in the dashboard, confirm the Bearer prefix, and check for stray whitespace.

Unknown model (400, model_not_found)

The model id is not available. List valid ids with GET /v1/models. Note that model ids are prefixed, for example openai/gpt-5.

Unsupported parameter (400, invalid_request_error)

Some models reject a parameter. For example, newer OpenAI models (GPT-5, o3, o4) require max_completion_tokens instead of max_tokens. Check the model’s supported_parameters in /v1/models.

Rate limited (429)

Back off and retry with exponential backoff, and reduce your request rate.

Upstream unavailable (502, upstream_error)

The upstream provider failed to respond. Retry, or try another model.

Best practices

Branch on the HTTP status and the error.type, not on the message text.
Retry only transient errors (429, 5xx) with backoff.
Keep keys in environment variables and never log them.

Core

Privacy

Migration

Integrations

Error response format

Status codes

Handle errors with the SDK

Retry transient errors

Common cases

Best practices

​Error response format

​Status codes

​Handle errors with the SDK

​Retry transient errors

​Common cases

​Best practices

Error response format

Status codes

Handle errors with the SDK

Retry transient errors

Common cases

Best practices