Die Form eines Fehlers
Fehler kommen als JSON mit einem error-Objekt. Die meisten antworten in der Form der Plattform; Audio, Bilder, Entscheidungen und einige Inference-Fehler antworten in der von OpenAI. Beide enthalten einen code: Verzweige nach ihm, nie nach der Meldung.
{
"error": {
"code": "model-not-found",
"category": "client",
"message": "no active deployment serves this model for the operation",
"request_id": "01K7YQ4D8M2P6S9V3X5Z7B1C4F"
}
}Status
| Status | Typische Fehlercodes | Was zu tun ist |
|---|---|---|
| 400 | invalid-request | Korrigiere die Anfrage; wiederhole sie nicht unverändert. |
| 401 | api-key-invalid, api-key-unknown, api-key-revoked | Prüfe den Key und die Region. Siehe Authentifizierung. |
| 402 | payment-required, credits-exhausted | Schließe ein Abonnement ab oder stocke das Guthaben für zusätzliche Modelle auf. |
| 403 | policy-denied, team-not-selectable | Dem Key-Inhaber fehlt die Berechtigung, oder sende X-Team-Id. |
| 404 | model-not-found | Das Modell bedient diesen Endpoint nicht oder steht deiner Organisation nicht zur Verfügung: Prüfe GET /v1/models. |
| 413 | request-body-too-large | JSON-Bodys bis zu 8 MiB, Audio-Uploads bis zu 25 MiB. |
| 429 | rate-limit-exceeded, *-concurrency-exceeded, provider-rate-limited | Wiederhole mit Backoff oder sende weniger Anfragen gleichzeitig. |
| 500 | internal-error | Wiederhole einmal; besteht der Fehler weiter, wende dich mit der Request-ID an den Support. |
| 502 | forwarder-failed | Das Modell hat etwas Ungültiges geantwortet. Wiederhole mit Backoff. |
| 503 | provider-unavailable | Gerade ist kein gesundes Modell verfügbar. Wiederhole mit Backoff. |
| 503 | model-not-priced | Das zusätzliche Modell hat noch keinen Preis. Nicht wiederholen; wende dich an den Support. |
| 504 | provider-timeout | Das Modell hat nicht rechtzeitig geantwortet. Wiederhole oder verkürze die Anfrage. |
Mit Backoff wiederholen
Wiederhole nur 429, 503 provider-unavailable und 504 und warte dabei jedes Mal länger. Die offiziellen OpenAI-Clients wiederholen bereits von sich aus zweimal (max_retries); dies ist eine längere Strategie für 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
Jede Antwort enthält einen X-Request-ID-Header. Sende eine eigene (eine ULID), um eine Anfrage mit deinen Logs zu verknüpfen, oder lies die, die die Plattform vergeben hat. Nenne sie, wenn du den Support kontaktierst, und finde die Anfrage damit im 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