Errors

Error Response Format

When an API request fails, OpenModel returns a JSON error response with the following structure:

Web API Errors

All /web/v1 endpoints return errors in OpenModel's standard format:

{
  "success": false,
  "data": null,
  "error": {
    "code": "UNAUTHORIZED",
    "msg": "API key is invalid or has been revoked",
    "detail": "optional additional detail"
  }
}

Proxy API Errors

Proxy endpoints (/v1/responses, /v1/messages, /v1beta/models/*) return errors in the format matching the requested API, so that SDK error handling works as expected.

OpenAI format (/v1/responses):

{
  "error": {
    "message": "Invalid API key provided",
    "type": "invalid_request_error",
    "code": "invalid_api_key"
  }
}

Anthropic format (/v1/messages):

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

Gemini format (/v1beta/models/*):

{
  "error": {
    "code": 401,
    "message": "Invalid API key provided",
    "status": "UNAUTHENTICATED"
  }
}

Error Codes

Error codes are string identifiers used in the error.code field of Web API responses.

Common Errors

Authentication Errors

Resource Errors

Validation Errors

Business Errors

Proxy Gateway Errors

When using the proxy endpoints (/v1/responses, /v1/messages, /v1beta/models/*), errors are returned in the provider-specific format rather than the standard Web API format. The HTTP status codes indicate the error type:

HTTP Status Codes

OpenModel uses standard HTTP status codes:

Handling Errors

Retry Strategy

For transient errors (429, 500, 502, 503, 504), implement exponential backoff with jitter:

import time
import random
from openai import OpenAI, APIError, RateLimitError

client = OpenAI(
    base_url="https://api.openmodel.ai/v1",
    api_key="your-api-key",
)

def create_with_retry(max_retries=3):
    for attempt in range(max_retries):
        try:
            return client.responses.create(
                model="gpt-5.4",
                input="Hello, world!",
            )
        except RateLimitError:
            if attempt == max_retries - 1:
                raise
            wait = (2 ** attempt) + random.random()
            print(f"Rate limited, retrying in {wait:.1f}s...")
            time.sleep(wait)
        except APIError as e:
            if e.status_code in (500, 502, 503, 504) and attempt < max_retries - 1:
                wait = (2 ** attempt) + random.random()
                print(f"Provider error, retrying in {wait:.1f}s...")
                time.sleep(wait)
            else:
                raise

response = create_with_retry()

Best Practices

• Check error codes programmatically -- Use error.code (Web API) or the format-specific error types (Proxy API) for control flow, not the human-readable message.
• Implement exponential backoff -- For rate limits (429) and server errors (500, 502, 503, 504), wait with increasing delays between retries.
• Set reasonable timeouts -- Configure client-side timeouts to handle slow upstream providers gracefully.
• Monitor your usage -- Use the Dashboard to track your API key usage and set up alerts before hitting rate limits or running out of balance.
• Log error responses -- Record the full error response for debugging purposes, especially for intermittent issues.