Störungen der OCR API lassen sich grob in drei Gruppen teilen: Anfragen, die gar nicht angenommen werden (401, 413, 415), Anfragen, die gedrosselt werden oder in ein Timeout laufen (429, 5xx), und Anfragen, die erfolgreich sind, deren Ergebnis aber unbrauchbar ist (leere Erkennung, Zeichensalat, geringe Konfidenz). Die ersten beiden Gruppen lassen sich am Statuscode erkennen; die dritte wird am häufigsten fälschlich für einen Defekt der Schnittstelle gehalten.

Dieser Beitrag beschreibt je Symptom die Prüfreihenfolge, Methoden zur Bildvorverarbeitung, die Retry-Strategie und die Logfelder; am Ende steht ein direkt wiederverwendbarer Fehlerbehandlungscode.

Hinweis: OCR-Schnittstellen, Fehlercodes und Kontingentregeln unterscheiden sich je nach Anbieter deutlich. Der Beitrag beschreibt das übliche Verhalten im Oktober 2026; maßgeblich sind die Anbieterdokumentation und die tatsächliche Antwort. OpenAI, Google, Microsoft, Alibaba Cloud, Tencent Cloud, Baidu AI Cloud, Tesseract und PaddleOCR sind Marken oder Produktnamen ihrer jeweiligen Inhaber und werden hier nur zur technischen Erläuterung genannt.

1. Zuerst vier Belege sichern

Vor dem Retry nicht hektisch neu senden, sondern zuerst diese Informationen festhalten:

  • HTTP-Statuscode sowie error.code und error.message im Antwortkörper;
  • Request-ID oder x-request-id aus den Antwortheadern;
  • Format, Dateigröße, Pixelmaße und EXIF-Ausrichtung des Originalbilds;
  • Aufrufzeitpunkt, verwendete Endpunktadresse und Modellname.
Statuscode Häufige Bedeutung Zuerst prüfen
400 Parameter oder Bildinhalt ungültig Base64, URL, Feldnamen, ob das Bild beschädigt ist
401 Authentifizierung fehlgeschlagen Ob der Key fehlt, abgelaufen ist oder Leerzeichen enthält
403 Keine Berechtigung oder Kontingent begrenzt Modellrechte, Projektstatus, Kontostand
413 Request-Body oder Datei zu groß Dateigröße, Pixelmaße, PDF-Seitenzahl
415 Nicht unterstützter Medientyp Content-Type, Dateiendung, tatsächliche Kodierung
429 Drosselung oder Parallelitätslimit QPS, Parallelität, Retry-After
500/502/503/504 Upstream-Störung oder Timeout Retry, Degradation, Statusseite

2. 401 und 403: erst Identität, dann Berechtigung

401 bedeutet, dass der Server den Key nicht akzeptiert. Häufige Ursachen: Im Header fehlt Authorization: Bearer, beim Kopieren sind Leerzeichen oder Zeilenumbrüche entstanden, die Umgebungsvariable ist leer, der Key wurde rotiert, oder ein Key der Plattform A wird an die Adresse von Plattform B gesendet.

Prüfen Sie zuerst mit einer minimalen Anfrage und raten Sie nicht im vollständigen Geschäftsablauf. Entscheidend ist der Wert, der tatsächlich gesendet wird, nicht nur der Inhalt der Konfigurationsdatei. 403 bedeutet dagegen meist: Der Key ist gültig, hat aber keine Berechtigung für dieses Modell oder diesen Endpunkt, oder das Konto ist kontingentiert beziehungsweise das Projekt deaktiviert.

Beachten Sie außerdem: Gateway-Adressen und native Anbieteradressen lassen sich in der Regel nicht mit demselben Key mischen. Beim Adresswechsel müssen Key, Modellname und Request-Pfad gemeinsam geprüft werden.

3. 413 und 415: Datei zu groß, Format falsch

413 bedeutet nicht „das Bild ist nicht erkennbar“, sondern die Anfrage wird bereits auf Transportebene abgelehnt. Typische Auslöser:

  • Ein einzelnes Bild überschreitet die Größenobergrenze der Schnittstelle;
  • die Pixelmaße sind zu groß und der Speicher nach dem Dekodieren läuft über;
  • die PDF-Datei hat zu viele Seiten oder es werden mehrere Seiten auf einmal hochgeladen;
  • durch Base64 wächst der Body um etwa ein Drittel, sodass ein zuvor knapp zulässiges Bild die Grenze überschreitet.

415 hängt meist am Format: Die Schnittstelle akzeptiert nur JPG und PNG, gesendet wurde HEIC, TIFF oder BMP; oder die Dateiendung lautet JPG, der Inhalt ist aber WebP; oder Content-Type ist application/json, während die Schnittstelle multipart/form-data erwartet.

Für die Bildvorverarbeitung empfiehlt sich diese Reihenfolge:

  1. Das Bild mit einer Bildbibliothek einlesen und das echte Format bestimmen, nicht der Dateiendung vertrauen.
  2. Proportional über die lange Kante begrenzen, zum Beispiel zuerst auf 2000–3000 Pixel reduzieren und dann testen.
  3. Die EXIF-Ausrichtung korrigieren, damit liegender Text nicht zu einem leeren Ergebnis führt.
  4. In ein unterstütztes Format konvertieren und die Kompressionsqualität kontrollieren, ohne die Schrift unscharf zu machen.
  5. Mehrseitige PDFs aufteilen und Seite für Seite verarbeiten oder eine Schnittstelle für vollständige Dokumente verwenden.
  6. Größe und Abmessungen vor und nach der Verarbeitung protokollieren, um später zu erkennen, an welcher Stufe die Grenze überschritten wurde.

Bilder sollten nicht so stark komprimiert werden, dass sie unlesbar werden, nur um 413 zu vermeiden. Nach zu starker Kompression kleben Schriftstriche zusammen; die Schnittstelle antwortet dann erfolgreich, liefert aber schlechte Qualität.

4. 429: Drosselung, Parallelität und Retry-Takt

429 bedeutet im Kern „zu viele oder zu schnelle Anfragen“. Übliche Dimensionen sind Anfragen pro Sekunde, Anfragen pro Minute, Parallelität sowie Kontingente nach Token oder Seiten. Selbst wenn das Gesamtvolumen passt, kann eine kurzfristige Parallelitätsspitze die Drosselung auslösen.

Grundregeln:

  • Retry-After lesen und, falls vorhanden, entsprechend warten;
  • sonst exponentielles Backoff mit zufälligem Jitter, damit nicht alle Clients gleichzeitig erneut senden;
  • nur 429 und 5xx erneut versuchen; Retries bei 401, 413 und 415 sind sinnlos;
  • maximale Retry-Anzahl und Gesamt-Timeout setzen, damit sich Aufgaben nicht stapeln;
  • Lastspitzen in eine Warteschlange legen und entsprechend der Kapazität des Servers gleichmäßig senden.

Mehr Retries sind nicht automatisch besser. Bei Abrechnung pro Aufruf richtet sich die Frage, ob fehlgeschlagene Anfragen berechnet werden, nach den Regeln des Anbieters; blinde Retries können die Kosten erhöhen.

5. Timeouts und 5xx: Netzproblem oder Upstream-Problem

Bei Timeouts ist zwischen Verbindungs- und Lese-Timeout zu unterscheiden. Ein Verbindungs-Timeout deutet meist auf Netz, DNS, Proxy oder Firewall hin; ein Lese-Timeout bedeutet, dass die Anfrage angekommen ist, die Verarbeitung aber zu lange dauert. Das tritt häufig bei großen Bildern, mehrseitigen PDFs oder Warteschlangen beim Upstream auf.

Für OCR-Anfragen sollte ein eigenes Timeout gesetzt werden, nicht das kurze Timeout gewöhnlicher Text-Schnittstellen. Synchrone Endpunkte eignen sich für kleine Bilder; für große Dokumente sind asynchrone Aufgaben mit Polling deutlich robuster. Bei 5xx ein- bis zweimal erneut versuchen; bleibt es erfolglos, auf den Ausweichweg wechseln und die Request-ID für die Klärung mit dem Anbieter protokollieren.

6. Leere Erkennung: Erfolgreiche Anfrage heißt nicht brauchbares Ergebnis

„Leere Erkennung“ wird am häufigsten falsch eingeschätzt. Die Schnittstelle antwortet mit 200, der Text ist aber eine leere Zeichenkette, enthält nur Satzzeichen oder alle Felder sind null. Prüfen Sie in dieser Reihenfolge:

  • Enthält das Bild überhaupt Text? Das Originalbild zuerst manuell öffnen und ausschließen, dass es eine leere Seite oder ein reines Foto ist.
  • Stimmt die Ausrichtung? Handyfotos enthalten oft Rotationsinformationen, die der Server möglicherweise nicht über EXIF berücksichtigt.
  • Ist die Schrift zu klein? Kleine Zeichen in einer Seitenminiatur lassen sich nach Vergrößerung und Zuschnitt oft erkennen.
  • Ist der Kontrast zu niedrig? Hellgraue Schrift, Schatten, Reflexionen und Durchscheinen senken die Trefferquote.
  • Passt die Sprache? Ein chinesisches Modell erkennt russische oder englische Belege unter Umständen nur bruchstückhaft.
  • Ist das Layout zu ungewöhnlich? Mehrspaltige, vertikale, tabellarische oder von Stempeln überlagerte Dokumente bereiten klassischer OCR häufig Probleme.
  • Liefert die Schnittstelle nur strukturierte Felder? Manche Endpunkte legen den Volltext in einem anderen Feld ab, während der Code nur text liest.

Ist das Bild klar, die Ausrichtung korrekt und die Sprache passend, das Ergebnis aber weiterhin leer, sollte eskaliert werden: Vorverarbeitungsparameter ändern, Modell wechseln, auf multimodale Extraktion umstellen oder manuelle Prüfung einschalten. Nicht auf gut Glück „noch einmal aufrufen“.

Auch geringe Konfidenz muss behandelt werden. Setzen Sie Schwellenwerte pro Feld; Werte darunter gehen in eine manuelle Warteschlange. Beträge, Ausweisnummern und Datumsangaben sollten format- und kreuzgeprüft werden. Nur wenn die Konfidenzverteilung im Log steht, lässt sich erkennen, ob die Qualität allmählich nachlässt oder von Anfang an schlecht war.

7. Wiederverwendbarer Fehlerbehandlungscode

Das folgende Beispiel geht davon aus, dass die Schnittstelle multipart/form-data akzeptiert; Pfad und Feldnamen sind gemäß Anbieterdokumentation anzupassen.

import random
import time
import requests

FATAL = {400, 401, 403, 413, 415}
RETRYABLE = {429, 500, 502, 503, 504}

def ocr_call(image_bytes, api_key, endpoint, max_retries=5):
    last_error = None
    for attempt in range(max_retries):
        try:
            resp = requests.post(
                endpoint,
                headers={"Authorization": f"Bearer {api_key}"},
                files={"file": ("page.png", image_bytes, "image/png")},
                timeout=(5, 90),  # Verbindung 5 s, Lesen 90 s
            )
        except requests.Timeout as exc:
            last_error = exc
        else:
            if resp.status_code in FATAL:
                raise RuntimeError(f"fatal_{resp.status_code}: {resp.text[:300]}")
            if resp.status_code == 200:
                data = resp.json()
                text = (data.get("text") or "").strip()
                if not text:
                    raise ValueError("empty_result: check rotation, crop and format")
                return data
            if resp.status_code not in RETRYABLE:
                raise RuntimeError(f"unexpected_{resp.status_code}")
            last_error = RuntimeError(resp.text[:300])

        retry_after = resp.headers.get("Retry-After") if "resp" in locals() else None
        wait = float(retry_after) if retry_after else min(2 ** attempt + random.random(), 30)
        time.sleep(wait)

    raise RuntimeError(f"retry_exhausted: {last_error}")

Der Code wartet nur bei wiederholbaren Fehlern und schlägt bei 401, 413 und 415 sofort fehl. Ein „leeres Ergebnis“ wird als fachliche Ausnahme behandelt, die eine manuelle Prüfung erfordert, nicht als Netzwerkfehler.

8. Was Logs und Monitoring erfassen sollten

Mindestens zu protokollieren: Request-ID, Statuscode, Fehlercode, Laufzeit, Bildabmessungen, Dateigröße, Retry-Anzahl, Anzahl erkannter Zeichen, durchschnittliche Konfidenz und ob eine manuelle Prüfung erfolgte. Eine Gruppierung nach Endpunkt und Modell zeigt, ob bestimmte Bildtypen problematisch sind oder ein Upstream instabil ist.

Drei Alarme sind sinnvoll: sprunghafter Anstieg der Fehlerrate, sprunghafter Anstieg der Leerergebnis-Rate und sprunghafter Anstieg der P95-Latenz. Wer nur die durchschnittliche Laufzeit beobachtet, übersieht den Long Tail — und genau dort treten OCR-Timeouts häufig auf.

9. Häufige Fragen

Warum schlägt 401 auch mit neuem Key fehl?

Prüfen Sie zuerst den tatsächlich gesendeten Header-Wert und danach, ob Key und Endpunktadresse zusammenpassen. Gateway-Keys und native Anbieter-Keys lassen sich meist nicht mischen; außerdem kann eine alte Prozessinstanz die Umgebungsvariable zwischengespeichert haben.

Warum meldet 413 auch nach der Kompression eine zu große Datei?

Prüfen Sie Pixelmaße, PDF-Seitenzahl und Base64-Aufblähung. Manchmal liegt die Dateigröße unter der Grenze, aber die Auflösung nach dem Dekodieren überschreitet das Limit; dann zuerst skalieren und erneut hochladen.

Warum wird 429 trotz Retries weiter ausgelöst?

Prüfen Sie, ob alle Clients gleichzeitig erneut senden und ob die Parallelität das Limit überschreitet. Zufälliger Jitter, Warteschlangen und eine Obergrenze für die Parallelität helfen meist mehr als zusätzliche Retries.

Das Bild ist gut lesbar — warum ist die Erkennung leer?

Prüfen Sie zuerst Ausrichtung, Sprache, Kontrast und ob der Code das falsche Antwortfeld liest. Ein scharfes, aber gedrehtes, reflektierendes oder sprachlich unpassendes Bild kann trotzdem ein leeres Ergebnis liefern.

Werden Retries doppelt berechnet?

Das hängt von den Abrechnungsregeln des Anbieters und davon ab, ob die Anfrage bereits verarbeitet wurde. Bei einem Timeout, der möglicherweise erfolgreich war, zuerst den Aufgabenstatus prüfen oder die Request-ID abgleichen und erst dann über einen Retry entscheiden.

Nächster Schritt

Nach der Stabilisierung der Fehlersuche empfiehlt es sich, OCR-Aufrufe in einer gemeinsamen Client-Schicht zu bündeln: einheitliche Timeouts, Retries, Logs und Degradation statt einer eigenen Lösung pro Modul. Wer mehrere Vision-Modelle über einen Zugang nutzen möchte, kann den ZSQH AI Gateway einsetzen; die Registrierung ist unter /sign-up erreichbar, Modelle und Abrechnung unter /pricing.

Weiterlesen: