The shape of an error
Errors come as JSON with an error object. Most answer in the platform's shape; audio, images, decisions and some inference errors answer in OpenAI's. Both carry a code: branch on it, never on the message.
{
"error": {
"code": "model-not-found",
"category": "client",
"message": "no active deployment serves this model for the operation",
"request_id": "01K7YQ4D8M2P6S9V3X5Z7B1C4F"
}
}Statuses
| Status | Typical codes | What to do |
|---|---|---|
| 400 | invalid-request | Fix the request; do not retry it unchanged. |
| 401 | api-key-invalid, api-key-unknown, api-key-revoked | Check the key and the region. See Authentication. |
| 402 | payment-required, credits-exhausted | Subscribe, or top up the credits of additional models. |
| 403 | policy-denied, team-not-selectable | The key's owner lacks the permission, or send X-Team-Id. |
| 404 | model-not-found | The model does not serve this endpoint, or is not yours: check GET /v1/models. |
| 413 | request-body-too-large | JSON bodies up to 8 MiB, audio uploads up to 25 MiB. |
| 429 | rate-limit-exceeded, *-concurrency-exceeded, provider-rate-limited | Retry with backoff, or send fewer requests at once. |
| 500 | internal-error | Retry once; if it persists, contact support with the request id. |
| 502 | forwarder-failed | The model answered something invalid. Retry with backoff. |
| 503 | provider-unavailable | No healthy model right now. Retry with backoff. |
| 503 | model-not-priced | The additional model has no price yet. Do not retry; contact support. |
| 504 | provider-timeout | The model did not answer in time. Retry, or shorten the request. |
Retry with backoff
Retry only 429, 503 provider-unavailable and 504, waiting longer each time. The official OpenAI clients already retry twice on their own (max_retries); this is a longer policy for batch jobs:
import random
import time
from openai import APIStatusError, OpenAI
RETRYABLE = {429, 503, 504}
def create_with_retries(client: OpenAI, attempts: int = 5, **request):
"""Retries only what can succeed later: limits, an unavailable or slow model."""
for attempt in range(attempts):
try:
return client.chat.completions.create(**request)
except APIStatusError as error:
if error.status_code not in RETRYABLE or attempt == attempts - 1:
raise
time.sleep(min(30, 2**attempt) + random.random()) # exponential backoff with jitterRequest ids
Every answer carries an X-Request-ID header. Send your own (a ULID) to tie a request to your logs, or read the one the platform minted. Quote it when you contact support, and find the request with it in the request log.
curl
curl -i "$CCSIO_BASE_URL/chat/completions" \
-H "Authorization: Bearer $CCSIO_API_KEY" \
-H "X-Request-ID: 01K7YQ4D8M2P6S9V3X5Z7B1C4F" \
-H "X-Session-Id: support-ticket-4312" \
-H "Content-Type: application/json" \
-d '{"model": "qwen3.8-flash-next", "messages": [{"role": "user", "content": "Hi"}]}'
# HTTP/2 200
# x-request-id: 01K7YQ4D8M2P6S9V3X5Z7B1C4F