Error Handling

When a request fails, Claudexia returns an error response with details about what went wrong. The format depends on which endpoint you used.

Anthropic Error Format

Errors from /v1/messages:

json

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "max_tokens: Field required"
  }
}

OpenAI Error Format

Errors from /v1/chat/completions:

json

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

Common Error Codes

HTTP Status	Error Type	Description
`400`	`invalid_request_error`	The request body is malformed or missing required fields (e.g. max_tokens, messages).
`401`	`authentication_error`	Invalid or missing API key. Ensure your key starts with sk_cdx_.
`403`	`permission_error`	The requested model is not allowed on your plan, or your IP address is blocked.
`429`	`rate_limit_error`	You have exceeded your rate limit. Back off and retry after the time indicated in the Retry-After header.
`500`	`api_error`	Internal server error. This is a bug on our side — retry the request or contact support if it persists.
`529`	`overloaded_error`	The API is temporarily overloaded. Retry with exponential backoff.

Retry Strategy

We recommend the following retry approach:

429 and 529 — Retry with exponential backoff starting at 1 second: 1s, 2s, 4s, 8s, up to 60s max. Respect the Retry-After header if present.
500 — Retry up to 3 times with a 1-second delay. If the error persists, it's likely a transient issue that will resolve on its own.
400, 401, 403 — Do not retry. Fix the request or check your API key and permissions.

python

import time
import requests

def call_api(payload, max_retries=3):
    for attempt in range(max_retries):
        response = requests.post(
            "https://api.claudexia.tech/v1/messages",
            headers={
                "x-api-key": "sk_cdx_YOUR_KEY",
                "anthropic-version": "2023-06-01",
                "Content-Type": "application/json",
            },
            json=payload,
        )
        if response.status_code == 200:
            return response.json()
        if response.status_code in (429, 529):
            wait = int(response.headers.get("Retry-After", 2 ** attempt))
            time.sleep(wait)
            continue
        if response.status_code >= 500:
            time.sleep(1)
            continue
        # 4xx client errors — don't retry
        response.raise_for_status()
    raise Exception("Max retries exceeded")

Streaming

Rate Limits