Die Rerank-Schnittstelle hat keinen so einheitlichen Standard wie Chat Completions; derselbe Code kann bei einem anderen Anbieter 404 oder 422 liefern. Bei der Diagnose zuerst nach HTTP-Statuscode schichten und danach die „stillen“ Fehler behandeln, bei denen 200 zurückkommt, das Ergebnis aber falsch ist. Dieser Beitrag gliedert nach Authentifizierung, Kandidatenmenge, Rate-Limiting, Timeout und leeren Ergebnissen und liefert am Ende wiederverwendbaren Retry-Code sowie eine Log-Checkliste. Modelle und Preise entnehmen Sie unseren Modellpreisen.

Hinweis: Cohere, Jina, Voyage und weitere genannte Namen sind Marken ihrer jeweiligen Inhaber; dieser Beitrag dient nur der technischen Diskussion. Endpunktpfade, Limits und Fehlercodes können sich mit Versionen ändern; maßgeblich ist die Dokumentation des jeweiligen Anbieters.

1. Fünf Problemklassen zuerst trennen

Symptom Häufiger Statuscode Typische Ursache Reihenfolge der Behandlung
Authentifizierung fehlgeschlagen 401, 403 falscher Key, fehlender Header, Modell nicht freigeschaltet zuerst Zugangsdaten und Rechte prüfen
Anfrage abgelehnt 400, 422 Kandidatenmenge zu groß, Felder passen nicht, Dokumente leer Request-Body und Limits prüfen
Pfadfehler 404 Endpunkt falsch, Modellname veraltet, Base URL falsch zusammengesetzt mit offizieller Dokumentation abgleichen
Rate-Limit oder Kontingent 429 plötzliche Parallelität, gemeinsamer Key, Retry-Sturm Backoff, Parallelität senken
Timeout oder Upstream-Fehler 504, 5xx zu viele Kandidaten, zu lange Dokumente, Upstream überlastet Anfrage verkleinern, begrenzt wiederholen
Leeres Ergebnis 200 ungültiges top_n, falsches Feld gelesen, Dokumente gefiltert Assertions und Warnungen ergänzen

Logs sollten mindestens Zeitpunkt, Endpunkt, Modell, Dokumentanzahl, Gesamtzeichenzahl, top_n, Statuscode, Dauer, Retry-Anzahl und Request-ID enthalten. Vollständige Keys nicht protokollieren und Nutzerdokumente nicht in voller Länge ausgeben.

2. 401 und 403: zuerst Authentifizierung, dann Berechtigung

401 bedeutet, dass die Identität nicht verifiziert wurde; Modellfähigkeit und Guthaben spielen meist keine Rolle. In dieser Reihenfolge prüfen:

  1. Verwendet der Header Authorization: Bearer mit dem Key? Manche Gateways verlangen x-api-key.
  2. Enthält der Key Leerzeichen, Zeilenumbrüche oder zusätzliche Anführungszeichen? Beim Kopieren aus Chatfenstern passiert das leicht.
  3. Wird die Umgebungsvariable durch lokale Konfiguration oder die Deployment-Plattform überschrieben? Nutzen Online und Lokal unterschiedliche Keys?
  4. Ist der Key für die Rerank-Schnittstelle freigeschaltet? Manche Konten haben nur Chat-Rechte, kein Rerank-Recht.
  5. Ist der Endpunkt korrekt? /v1/rerank und /v2/rerank können unterschiedliche Formate haben; wird die Base URL der Chat-Schnittstelle einfach um /rerank ergänzt, sind 404 oder 401 wahrscheinlich.

403 bedeutet, dass die Identität gültig ist, die Berechtigung aber fehlt. Prüfen: Modellfreischaltung, IP-Whitelist, Projektberechtigung und Zahlungsstatus. 401 nicht wiederholen; Retries erzeugen nur mehr Fehlerlogs und können Risikokontrollen auslösen. Zuerst mit einem minimalen curl-Aufruf testen, dann zum Anwendungscode zurückkehren.

3. 400 und 422: zu große Kandidatenmenge, unpassende Felder

Eine zu große Kandidatenmenge ist die häufigste Ursache für 400. Gehostete Schnittstellen haben meist Obergrenzen für Dokumentanzahl pro Aufruf, Token pro Dokument und Request-Größe. Cohere empfiehlt beispielsweise, pro Aufruf nicht mehr als eintausend Dokumente zu senden, und kürzt einzelne Dokumente standardmäßig auf 4096 Token; andere Anbieter haben abweichende Werte, die sich mit Modellversionen ändern. Vor der Integration die jeweilige Dokumentation prüfen. Bei Überschreitung ist nicht blindes Wiederholen richtig, sondern:

  • die Kandidatenmenge aufteilen, jeden Teil separat reranken und die Scores zusammenführen;
  • die Kandidaten bereits im Retrieval sinnvoll begrenzen, etwa auf fünfzig bis zweihundert;
  • überlange Dokumente vorher chunken oder kürzen, nicht eine ganze PDF in documents legen;
  • leere Strings, null, reine Leerzeichen und Duplikate entfernen.

Auch unpassende Felder führen zu 400 oder 422: top_n statt top_k oder umgekehrt; Jina und Cohere verwenden meist top_n, Voyage top_k. documents enthält Objekte statt Strings, oder id und text liegen auf der falschen Ebene. Ist top_n größer als die Dokumentanzahl, melden manche Schnittstellen einen Fehler, andere kürzen automatisch. Parameter wie return_documents, truncation oder max_tokens_per_doc werden nicht von jedem Anbieter unterstützt. NaN, Infinity und nicht maskierte Zeilenumbrüche im JSON führen ebenfalls zu Parse-Fehlern.

Vorgehen: den anonymisierten Original-Request-Body aufbewahren und die Parameter einzeln, jeweils nur eine Änderung pro Lauf, zum minimalen Beispiel hinzufügen.

4. 429: Rate-Limits, Kontingente und Retry-Stürme

429 bedeutet, dass die Anfrage gedrosselt wurde oder das Kontingent erschöpft ist. Häufige Ursachen: Anfragen pro Sekunde oder Parallelität über dem Tarif, tokenbasiertes Kontingent in Spitzenzeiten aufgebraucht, mehrere Dienste teilen einen Key, clientseitige Retries ohne Backoff. Zuerst Retry-After und Kontingentfelder in den Antwort-Headern prüfen, dann entscheiden, ob gewartet oder die Parallelität gesenkt wird.

Reihenfolge:

  1. Klären, ob es ein Limit pro Key oder ein Kontingent auf Kontoebene ist.
  2. Retries auf exponentielles Backoff mit Jitter umstellen und Retry-After respektieren.
  3. Parallelität begrenzen und Spitzen über eine Queue abfangen, statt unbegrenzt zu wiederholen.
  4. Batch-Aufgaben in Nebenzeiten legen; Offline-Evaluation und Online-Traffic trennen.
  5. Für kritische Dienste einen Fallback vorbereiten: Reranking überspringen und die Retrieval-Reihenfolge behalten.

Nicht mit festen Ein-Sekunden-Intervallen wiederholen. Wenn viele Instanzen gleichzeitig wiederholen, entsteht ein Retry-Sturm, der ein kleines Limit zu einer anhaltenden Störung macht.

5. Timeouts, 504 und 5xx

Bei Timeouts ist zwischen Verbindungs- und Lese-Timeout zu unterscheiden. Verbindungs-Timeouts deuten meist auf Netzwerk, DNS, Proxy oder TLS; Lese-Timeouts eher auf zu viele Kandidaten, zu lange Dokumente, Upstream-Warteschlangen oder Kaltstart des Modells. 504 bedeutet meist, dass das Gateway keine Antwort vom Upstream erhält – unabhängig vom eigenen Client-Timeout.

Diagnosereihenfolge:

  1. Mit einer minimalen Anfrage testen: eine Query, fünf kurze Dokumente, um auszuschließen, dass das Netzwerk vollständig gestört ist.
  2. Dokumentanzahl schrittweise erhöhen und den Knick bei der Dauer finden.
  3. Länge einzelner Dokumente und Gesamt-Token prüfen und bei Bedarf kürzen.
  4. Prüfen, ob der Client-Timeout kürzer ist als die serverseitige Bearbeitungszeit.
  5. Bei 5xx und Timeouts begrenzt wiederholen und nach Erreichen der Schwelle degradieren.
  6. Request-ID und die vom Upstream zurückgegebene Trace-ID protokollieren, um mit dem Anbieter abgleichen zu können.

Reranking ist üblicherweise keine Streaming-Schnittstelle; lange Laufzeiten lassen sich nicht durch Streaming verdecken. Für latenzkritische Dienste gehört das Reranking in eine asynchrone Kette oder nur auf die ersten Dutzend Kandidaten.

6. Status 200, aber leeres oder falsches Ergebnis

Diese stillen Fehler sind schwerer zu erkennen: documents ist ein leeres Array und die Schnittstelle liefert ein leeres Ergebnis; top_n ist 0 oder negativ; alle Dokumente werden durch fachliche Filter ausgeschlossen; das Antwortfeld wird falsch gelesen, mal results, mal data; index bezieht sich auf das ursprüngliche Dokumentarray, aber nach dem Sharding wurde der Offset vergessen; Score-Semantik unterscheidet sich, mal auf null bis eins normalisiert, mal Logits, und die Sortierrichtung kann abweichen; zurückgegeben wird der Dokumenttext statt des Index, und beim Deduplizieren werden gleiche Texte zusammengeführt.

Empfohlen sind clientseitige Assertions: Ergebnisanzahl nicht größer als top_n, jeder Index im gültigen Bereich, Scores gemäß der Anbieter-Semantik monoton. Bei Anomalien eine Zusammenfassung der Originalantwort protokollieren und nicht stillschweigend eine leere Liste zurückgeben.

7. Wiederverwendbarer Retry-Code

Das folgende Beispiel teilt Fehler in drei Klassen: Authentifizierungs- und Parameterfehler werden nicht wiederholt, 429 und 5xx mit Backoff, Timeouts begrenzt; nach erschöpften Retries wird auf die ursprüngliche Retrieval-Reihenfolge zurückgefallen.

import random
import time
import requests

def rerank(query, documents, top_n=10, model="<rerank-model>",
           url="<base-url>/v1/rerank", api_key="<key>"):
    payload = {"model": model, "query": query,
               "documents": documents, "top_n": top_n}
    headers = {"Authorization": f"Bearer {api_key}"}
    last_error = None
    for attempt in range(5):
        try:
            resp = requests.post(url, json=payload, headers=headers,
                                 timeout=(3.05, 30))
        except requests.Timeout as exc:
            last_error = exc
            time.sleep(min(2 ** attempt + random.random(), 20))
            continue

        if resp.status_code in (400, 401, 403, 404, 422):
            raise RuntimeError(f"Nicht wiederholbar {resp.status_code}: {resp.text[:300]}")
        if resp.status_code == 429 or resp.status_code >= 500:
            retry_after = resp.headers.get("Retry-After")
            wait = float(retry_after) if retry_after else min(
                2 ** attempt + random.random(), 20)
            time.sleep(wait)
            last_error = RuntimeError(f"Wiederholbar {resp.status_code}")
            continue

        data = resp.json()
        results = data.get("results") or data.get("data") or []
        if not results:
            return list(range(min(top_n, len(documents))))
        return [item["index"] for item in results[:top_n]]

    raise RuntimeError(f"Retries erschöpft: {last_error}")

# Der Aufrufer muss die Anbieterfelder anpassen, z. B. nutzt Voyage data und top_k.

Beim Reranking aufgeteilter Dokumente muss beim Zusammenführen der Index innerhalb des Shards um den Offset erhöht und anschließend gemeinsam sortiert werden.

8. Log- und Monitoring-Checkliste

Pro Aufruf mindestens erfassen: Zeitpunkt, Endpunkt, Modell, Dokumentanzahl, Gesamtzeichenzahl oder geschätzte Token, top_n, Statuscode, Fehlertyp, Dauer, Retry-Anzahl und Request-ID. Vollständige Keys nicht protokollieren und Nutzerdokumente nicht in voller Länge ins Log schreiben; für die Fehlersuche Hash, Länge und die ersten anonymisierten Zeichen erfassen.

Im Monitoring vier Kennzahlen beobachten: Anteil 429, Anteil Timeouts und 5xx, Anteil leerer Ergebnisse und P95-Latenz. Zusätzlich nach Geschäftsbereich aufteilen, damit eine häufige, wenig wertvolle Aufgabe nicht das Kontingent aufbraucht und Anomalien im Kerngeschäft verdeckt.

Häufige Fragen

Worin unterscheiden sich 401 und 403?

401 bedeutet, dass die Identität nicht verifiziert wurde, meist wegen fehlendem, falsch formatiertem oder ungültigem Key. 403 bedeutet, dass die Identität gültig ist, aber die Berechtigung fehlt – etwa Modell nicht freigeschaltet, IP nicht in der Whitelist, Projekt- oder Guthabenbeschränkung. Zuerst Authentifizierung, dann Berechtigung prüfen.

Was tun, wenn die Kandidatenmenge das Schnittstellenlimit überschreitet?

Clientseitig aufteilen, jeden Teil separat reranken und die Scores zusammenführen; dabei den Index um den Offset korrigieren. Grundsätzlicher ist es, die Menge bereits im Retrieval zu begrenzen – meist reichen einige Dutzend bis einige Hundert, nicht Tausende.

Wie viele Retries sind bei 429 sinnvoll?

Eine pauschale Zahl gibt es nicht. Empfohlen sind begrenzte Wiederholungen, etwa drei bis fünf, mit exponentiellem Backoff und Jitter sowie Beachtung von Retry-After; gleichzeitig die Parallelität begrenzen. Nach erschöpften Retries degradieren und Anfragen nicht unbegrenzt stapeln.

Kann eine Rerank-Schnittstelle bei Timeout wie ein Chat streamen?

Meist nicht. Reranking muss die gesamte Kandidatenmenge sehen, um eine stabile Rangfolge zu liefern; die meisten Schnittstellen antworten synchron. Bei Latenzempfindlichkeit Kandidatenzahl reduzieren, Dokumentlänge kürzen oder das Reranking in eine asynchrone Aufgabe verlagern.

Warum kommt 200, aber kein Ergebnis?

Zuerst prüfen, ob documents leer ist, top_n gültig ist und fachliche Filter alle Dokumente ausschließen; dann, ob das Antwortfeld falsch gelesen wird und ob beim Zusammenführen von Shards Indizes außerhalb des Bereichs liegen. Assertions und Warnungen bei leeren Ergebnissen sind wirksamer als nachträgliche Fehlersuche.

Nächster Schritt

Nach der Diagnose ein minimales Reproduktionsbeispiel und eine Regressionssuite fixieren, dann im ZSQH AI Gateway einen Test-Key anlegen und die Aufrufkette verifizieren; Abrechnung und Limits entnehmen Sie der Seite Modellpreise.

Weiterführende Informationen