L'interface Rerank n'a pas de standard aussi unifié que Chat Completions : le même code peut renvoyer 404 ou 422 chez un autre fournisseur. Pour diagnostiquer, séparez d'abord les codes HTTP, puis traitez les erreurs silencieuses du type « 200 mais résultat incorrect ». Cet article couvre cinq familles — authentification, jeu de candidats, limitation de débit, timeout et résultat vide — et se termine par un code de retry réutilisable et une checklist de logs. Modèles et prix de référence : tarifs des modèles.

Remarque : Cohere, Jina, Voyage et les autres noms cités sont des marques de leurs détenteurs respectifs ; cet article est purement technique. Chemins d'interface, quotas et codes d'erreur peuvent changer selon les versions ; référez-vous à la documentation du fournisseur concerné.

1. Distinguer d'abord cinq familles

Symptôme Codes fréquents Cause typique Ordre de traitement
Échec d'authentification 401, 403 Clé erronée, en-tête manquant, modèle non activé Corriger d'abord identifiants et droits
Requête refusée 400, 422 Jeu de candidats trop grand, champ incompatible, documents vides Vérifier corps de requête et quotas
Chemin erroné 404 Point d'entrée mal écrit, ancien nom de modèle, URL de base mal assemblée Comparer à la documentation
Limitation ou quota 429 Pic de concurrence, clé partagée, tempête de retries Backoff, réduire la concurrence
Timeout ou erreur amont 504, 5xx Trop de candidats, documents trop longs, amont surchargé Réduire la requête, retries limités
Réponse vide 200 top_n invalide, champ mal lu, documents filtrés Ajouter assertions et alertes

Les logs doivent au minimum contenir : horodatage, point d'entrée, modèle, nombre de documents, nombre total de caractères, top_n, code de statut, durée, nombre de retries et ID de requête. Ne journalisez jamais la clé complète ni le texte intégral des documents utilisateur.

2. 401 et 403 : vérifier l'authentification, puis les droits

401 signifie que l'identité n'a pas été validée ; cela n'a généralement rien à voir avec les capacités du modèle ou le solde. Procédez dans cet ordre :

  1. L'en-tête utilise-t-il Authorization: Bearer avec la clé ? Certaines passerelles exigent x-api-key.
  2. Y a-t-il un espace, un saut de ligne ou des guillemets superflus autour de la clé ? La copie depuis une fenêtre de discussion est la cause la plus fréquente.
  3. Une variable d'environnement est-elle écrasée par la configuration locale ou la plateforme de déploiement ? La production et le poste local utilisent-ils des clés différentes ?
  4. La clé a-t-elle accès à l'interface de reranking ? Certains comptes n'ont que les droits de conversation, sans Rerank.
  5. Le point d'entrée est-il correct ? /v1/rerank et /v2/rerank peuvent différer ; ajouter /rerank à l'URL de base d'une interface de chat produit facilement un 404 ou un 401.

403 signifie que l'identité est valide mais les droits insuffisants : vérifiez l'activation du modèle, la liste d'IP, les droits du projet et l'état de paiement. Ne retentez pas un 401 : cela gonfle les logs d'échec et peut déclencher la protection anti-abus. Faites d'abord passer un curl minimal, puis revenez au code métier.

3. 400 et 422 : lot trop grand, champs incompatibles

Un jeu de candidats trop grand est la première source de 400. Les interfaces hébergées imposent généralement des limites sur le nombre de documents par appel, les tokens par document et la taille du corps. Chez Cohere, par exemple, la documentation recommande de ne pas dépasser un millier de documents par appel, avec une troncature par défaut à 4096 tokens par document ; les valeurs diffèrent chez les autres fournisseurs et évoluent avec les versions. En cas de dépassement, la bonne réaction n'est pas de retenter aveuglément, mais de :

  • découper le jeu de candidats, reranger chaque fragment, puis fusionner par score ;
  • limiter les candidats dès le rappel, par exemple entre cinquante et deux cents ;
  • découper ou tronquer les documents très longs au lieu d'envoyer un PDF entier dans documents ;
  • supprimer les chaînes vides, les null, les espaces seuls et les doublons.

Un champ incompatible produit aussi un 400 ou 422 : top_n écrit top_k, ou l'inverse ; Jina et Cohere utilisent surtout top_n, Voyage top_k. documents reçoit un tableau d'objets au lieu d'un tableau de chaînes, ou les champs id et text sont mal placés. Si top_n dépasse le nombre de documents, certaines interfaces renvoient une erreur, d'autres tronquent automatiquement. Les paramètres return_documents, truncation, max_tokens_per_doc peuvent ne pas être pris en charge par le fournisseur actuel. Les NaN, Infinity et sauts de ligne non échappés dans le JSON provoquent également un échec d'analyse.

Méthode : conservez le corps de requête d'origine anonymisé, puis réintroduisez les paramètres un par un à partir d'un exemple minimal, en ne changeant qu'une variable à la fois.

4. 429 : limitation, quota et tempête de retries

429 indique une limitation de débit ou un quota épuisé. Causes fréquentes : requêtes par seconde ou concurrence supérieures au forfait, quota en tokens épuisé aux heures de pointe, clé partagée entre plusieurs services, retries clients sans backoff. Lisez d'abord Retry-After et les champs de quota dans les en-têtes, puis décidez d'attendre ou de réduire la concurrence.

Ordre de traitement :

  1. Déterminer s'il s'agit d'une limitation par clé ou d'un quota de compte.
  2. Passer les retries en backoff exponentiel avec jitter, en respectant Retry-After.
  3. Limiter la concurrence et lisser les pics par file d'attente, plutôt que retenter sans fin.
  4. Placer les tâches par lots aux heures creuses et séparer l'évaluation hors ligne du trafic en ligne.
  5. Prévoir une dégradation pour les activités critiques : ignorer le reranking et conserver l'ordre du rappel.

N'utilisez pas un retry fixe à une seconde qui sature tout. Plusieurs instances qui retentent ensemble créent une tempête de retries et transforment une petite limitation en panne durable.

5. Timeout, 504 et 5xx

Distinguez timeout de connexion et timeout de lecture. Le premier relève généralement du réseau, du DNS, du proxy ou de TLS ; le second vient plus souvent d'un jeu de candidats trop grand, de documents trop longs, d'une file d'attente amont ou d'un démarrage à froid du modèle. Un 504 signifie généralement que la passerelle n'a pas reçu de réponse de l'amont ; c'est distinct du timeout côté client.

Ordre de diagnostic :

  1. Tester avec une requête minimale : une query, cinq documents courts, pour vérifier que le réseau fonctionne.
  2. Augmenter progressivement le nombre de documents pour trouver le point d'inflexion.
  3. Vérifier la longueur par document et le total de tokens, tronquer si nécessaire.
  4. Vérifier que le timeout client n'est pas inférieur au temps de traitement serveur.
  5. Retenter un nombre limité de fois sur 5xx et timeout, puis dégrader au-delà du seuil.
  6. Enregistrer l'ID de requête et le trace ID renvoyé par l'amont pour le rapprochement avec le fournisseur.

Le reranking n'est généralement pas une interface de streaming : on ne peut pas masquer un temps long par un flux. Pour les activités sensibles à la latence, placez le reranking dans un chemin asynchrone ou ne rerangez que les premières dizaines de candidats.

6. 200 mais résultat vide ou incorrect

Ces erreurs silencieuses sont plus difficiles à voir : documents est un tableau vide et l'interface renvoie un résultat vide ; top_n vaut 0 ou un nombre négatif ; tous les documents sont exclus par un filtre métier ; le mauvais champ de réponse est lu, certains renvoient results, d'autres data ; index est la position dans le tableau d'origine, mais l'offset est oublié après découpage ; la sémantique des scores diffère, certains normalisent entre 0 et 1, d'autres renvoient des logits, et le sens du classement peut varier ; la réponse contient le texte du document au lieu de l'index, et la déduplication fusionne des textes identiques.

Ajoutez des assertions côté client : le nombre de résultats ne dépasse pas top_n, chaque index est dans les bornes, les scores sont monotones selon la sémantique du fournisseur. En cas d'anomalie, journalisez un résumé de la réponse brute ; ne renvoyez pas silencieusement une liste vide.

7. Un code de retry réutilisable

L'exemple classe les erreurs en trois catégories : pas de retry pour l'authentification et les paramètres, backoff pour 429 et 5xx, retries limités pour les timeouts ; une fois les retries épuisés, retour à l'ordre de rappel initial.

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"Non retentable {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"Retentable {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 épuisés : {last_error}")

# L'appelant doit adapter les champs au fournisseur, par exemple Voyage avec data et top_k.

En cas de reranking par fragments, ajoutez l'offset du fragment aux index avant la fusion et le tri final.

8. Checklist de logs et de supervision

Chaque appel doit enregistrer au minimum : horodatage, point d'entrée, modèle, nombre de documents, nombre total de caractères ou tokens estimés, top_n, code de statut, type d'erreur, durée, nombre de retries, ID de requête. Ne journalisez jamais la clé complète ni le texte intégral des documents ; pour diagnostiquer, enregistrez un hash, la longueur et les premiers caractères anonymisés.

Quatre indicateurs à suivre : proportion de 429, proportion de timeouts et 5xx, proportion de résultats vides, latence p95. Ventilez ensuite par ligne métier pour éviter qu'une tâche fréquente à faible valeur consomme le quota et masque une anomalie sur l'activité critique.

Questions fréquentes

Quelle différence entre 401 et 403 ?

401 signifie que l'identité n'est pas validée : clé absente, mal formée ou expirée. 403 signifie que l'identité est valide mais les droits insuffisants : modèle non activé, IP hors liste, projet ou solde limité. Corrigez d'abord l'authentification, puis les droits.

Que faire si le jeu de candidats dépasse la limite de l'interface ?

Découpez côté client, rerangez chaque fragment puis fusionnez par score en ajoutant l'offset aux index. La solution de fond est de limiter le nombre dès le rappel : quelques dizaines à quelques centaines suffisent généralement, n'envoyez pas un millier de documents au reranking.

Combien de retries sur 429 ?

Pas de réponse universelle. Prévoyez un nombre limité de tentatives, par exemple trois à cinq, avec backoff exponentiel et jitter, en respectant Retry-After, tout en limitant la concurrence. Après épuisement, dégradez ; ne laissez pas les requêtes s'accumuler sans fin.

Peut-on utiliser le streaming pour un timeout Rerank, comme en conversation ?

En général non. Le reranking doit parcourir tout le jeu de candidats pour produire un classement stable ; la plupart des interfaces répondent en synchrone. Si la latence est critique, réduisez les candidats, tronquez les documents ou déplacez le reranking vers une tâche asynchrone.

Pourquoi un 200 sans résultat ?

Vérifiez si documents est vide, si top_n est valide, si un filtre métier a exclu tous les documents ; vérifiez ensuite le champ de réponse lu et les index hors bornes lors de la fusion de fragments. Ajouter des assertions et une alerte de résultat vide est plus efficace qu'un diagnostic a posteriori.

Étapes suivantes

Une fois le diagnostic terminé, figez un cas de reproduction minimal et un jeu de régression, puis créez une clé de test sur ZSQH AI Gateway pour valider la chaîne d'appel ; facturation et quotas de référence : tarifs des modèles.

Lectures associées :