Fehler und Wiederholungen
HTTP-Fehler, Idempotenzschlüssel, sichere Wiederholungen und unklare Abrechnungen bei der FreeAIOCR API.
Diese Anleitungen gelten für Bild zu Text und Bild zu Tabelle. Eingaben, Formate und spezifische Fehler finden Sie in der jeweiligen API-Referenz.
Fehlerantworten
Beispiel einer JSON-Fehlerantwort:
{
"request_id": "b2c8ec98-2a36-4f87-99d2-3d7839b92518",
"error": {
"code": "insufficient_balance",
"message": "Recognition did not complete",
"required_reservation_usd": "0.011288000"
}
}HTTP-Statuscodes
| HTTP | error.code |
|---|---|
| 400 | invalid_request, invalid_idempotency_key, invalid_image |
| 401 | unauthorized |
| 402 | insufficient_balance |
| 403 | account_unavailable |
| 405 | invalid_request |
| 409 | idempotency_conflict, request_in_progress |
| 413 | image_too_large, input_limit_exceeded |
| 415 | unsupported_media_type |
| 422 | recognition_blocked |
| 429 | rate_limit_exceeded, concurrency_limit_exceeded |
| 502 | recognition_failed, output_truncated, empty_result, invalid_usage |
| 503 | service_unavailable, settlement_pending, export_failed |
| 504 | request_timeout |
| HTTP | Ursache | Maßnahme |
|---|---|---|
| 400 / 413 / 415 | Ungültige Anfrage, Bildgröße oder Dateiformat | Upload korrigieren oder Bild verkleinern |
| 405 | Falsche HTTP-Methode | POST verwenden |
| 401 | API-Schlüssel fehlt oder ist ungültig | Bearer-Schlüssel prüfen |
| 403 | Konto nicht verfügbar | Konto bestätigen oder Einschränkung beheben |
| 402 | Nicht genügend verfügbares Guthaben | Aufladen; error.required_reservation_usd und die Guthabenreservierung prüfen |
| 409 | Idempotenzkonflikt oder Vorgang läuft noch | Bei request_in_progress dieselbe ID und dasselbe Bild beibehalten und später wiederholen; bei Konflikt die Vorgangs-ID korrigieren |
| 429 | Anfrage- oder Parallelitätslimit erreicht | Retry-After beachten |
| 422 / bestätigter 502 | Bestätigter Erkennungsfehler | Keine Erkennungsgebühr; Fehler prüfen |
| 503 / 504 / unklar | Unklarer Dienst-, Abrechnungs- oder Timeout-Status | Nicht von Kostenfreiheit ausgehen; mit demselben Idempotency-Key und Bild wiederholen |
Fehler werden als JSON mit request_id, error.code und error.message zurückgegeben. Alle Antworten verwenden Cache-Control: no-store. Erkennung wird nicht gestreamt: Erfolg verwendet das gewählte Format, Fehler bleiben JSON. Bewahren Sie X-Request-Id für den Support auf.
Idempotenz
Idempotency-Key ist Ihre Vorgangs-ID: 16–128 ASCII-Buchstaben, Ziffern oder . _ : -. Neues Bild: neue eindeutige ID. Wiederholung: gleiche ID, ursprüngliche Bildbytes und MIME. Sie gilt kontoweit, auch bei Schlüsselwechsel. Innerhalb von 24 Stunden nach Annahme liefert ein abgeschlossener Vorgang ursprüngliche request_id, Ergebnis und Kosten mit Idempotency-Replayed: true zurück, ohne erneute Generierung oder Berechnung.
Verwenden Sie für jeden neuen Vorgang oder Endpunkt einen anderen Idempotency-Key. Derselbe Wert für Text und Tabellen führt zu 409 idempotency_conflict. Bei Formatwechseln desselben Vorgangs bleiben Schlüssel und Bild gleich.
Wiederholungsstrategie
Bei Netzwerkfehlern, request_in_progress oder settlement_pending dieselbe ID und dasselbe Bild beibehalten, Retry-After Sekunden warten und wiederholen. Bei unklarer Abrechnung keinen neuen Vorgang erstellen. Gespeicherte endgültige Fehler werden wiederholt; neue ID nur für einen bewussten Neustart nach bestätigtem Fehler. Nach 24 Stunden kann dieselbe ID einen neuen kostenpflichtigen Vorgang starten; offene Wiederherstellung verhindert weiter die Wiederverwendung.
Sichere Abrechnung
Bestätigte Erkennungsfehler kosten nichts; eine verlorene Antwort oder settlement_pending kann jedoch auf bereits erfolgte Abrechnung oder weiter reserviertes Guthaben hinweisen. Solange das Ergebnis unklar ist, keinen neuen Vorgang mit einem neuen Idempotency-Key starten. Mit ursprünglicher ID und Bild wiederholen und X-Request-Id für den Support aufbewahren.