Fehler und Wiederholungen

Sprache der Fehlermeldungen

Fehlertexte für Menschen können in der Sprache zurückkommen, die Sie wählen. Das betrifft genau drei Stellen: msg in der Antwort, errorMessage fehlgeschlagener Tasks (in recordInfo wie in Webhook-Zustellungen) und error.message in den Fehlerobjekten der kompatiblen APIs – im OpenAI-, Anthropic- wie im Google-Gemini-Format. Standard ist Englisch. Unterstützte Sprachcodes: en, zh-Hant, ja, ko, de, fr, es, pt-BR, ru.

Es ändert sich nur der lesbare Text. Die Werte von code und errorCode, type und code der OpenAI-kompatiblen Schicht, code und status der Gemini-kompatiblen Schicht sowie sämtliche Feldnamen bleiben in jeder Sprache gleich. Verzweigen Sie ausschließlich nach Codes und werten Sie keine Texte aus; halten Sie in Logs und Alarmen code und request_id fest. Welche Sprache tatsächlich verwendet wurde, zeigt der Antwort-Header Content-Language. Beispiel: Beim selben Fehler 40201 (Guthaben unzureichend) lautet msg standardmäßig „Insufficient balance“; mit Accept-Language: ja steht msg auf Japanisch, code bleibt 40201.

Die Sprache wird in dieser Reihenfolge bestimmt:

• Accept-Language-Header: gilt nur für die jeweilige Anfrage. Maßgeblich ist die übliche HTTP-Gewichtung: Gewählt wird die erkannte Sprache mit dem höchsten q-Wert. Regionale Varianten werden ihrer Sprache zugeordnet: de-DE zu de, pt-PT zu pt-BR, zh-TW, zh-HK und zh-Hant zu zh-Hant. Chinesisch gibt es nur in traditioneller Schrift; zh-CN und zh-Hans passen deshalb zu keiner Sprache, und der nächste Kandidat wird geprüft. * gilt als keine Präferenz.
• Kontoeinstellung: in der Konsole unter „Einstellungen → Sprache der API-Fehlermeldungen“. Sie gilt für jede Anfrage mit einem API-Schlüssel dieses Kontos, die keinen erkennbaren Accept-Language-Header mitsendet. Die meisten serverseitigen SDKs und curl senden diesen Header standardmäßig nicht; in der Praxis ist das daher der übliche Weg. Webhook-Zustellungen haben keinen Anfrage-Header und folgen immer der Kontoeinstellung.
• Trifft beides nicht zu, wird Englisch verwendet.

# Default: no Accept-Language, no account setting
HTTP/1.1 402 Payment Required
Content-Language: en

{ "code": 40201, "msg": "Insufficient balance", "request_id": "req_…" }

# The same request with one extra header
curl -X POST https://api.spicyapi.ai/api/v1/jobs/createTask \
  -H "Authorization: Bearer $SPICY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $SPICY_IDEMPOTENCY_KEY" \
  -H "Accept-Language: ja" \
  --data "$TASK_PAYLOAD"

HTTP/1.1 402 Payment Required
Content-Language: ja

{ "code": 40201, "msg": "残高が不足しています", "request_id": "req_…" }

Nicht wiederholen

400, 401, 403, 404, 40201, 40202 und 40301–40303 ändern sich erst nach Korrektur von Eingabe, Zugangsdaten, Berechtigung, Guthaben oder Limit. 413 bedeutet, dass der Body zu groß ist: nicht unverändert wiederholen, sondern verkleinern oder den Medien-Upload verwenden.

Wiederholbare Fehler

Bei 429 gilt Retry-After. HTTP 500/503 sowie die Business-Codes 500/50301 erfordern exponentielles Backoff mit Jitter. 409 ist operationsabhängig: Wiederholen Sie nur media pending oder den seltenen gleichzeitigen createTask-Konflikt mit unverändertem Idempotency-Key und Payload. Ein Schlüsselkonflikt mit anderem Payload ist nicht wiederholbar.

Bei Netzwerkfehlern während createTask bleibt der Idempotency-Key gleich. Derselbe Schlüssel mit anderem Payload führt zu 409.

Abrechnung

Vor der Task-Erstellung abgelehnte Anfragen kosten nichts. Nach Erstellung geben failed, expired und historische canceled-Datensätze die Reservierung vollständig frei. Neu angenommene Tasks können nicht abgebrochen werden; nur succeeded wird nach tatsächlicher Nutzung abgerechnet.