Opérations · 2026-09-01 · HippoAPI Documentation Team

Erreurs et tentatives

Classez les échecs d'API, capturez des preuves utiles et réessayez uniquement les requêtes transitoires qui peuvent être répétées en toute sécurité.

Forme de réponse d'erreur

Les réponses non-2xx utilisent un objet d'erreur avec un message lisible par l'homme et peuvent inclure un type, un code ou un ID de demande. Traitez l'état HTTP comme le premier signal de classification et conservez l'ID de la demande lorsqu'il est présent.

{
  "error": {
    "message": "Error description (request id: ...)",
    "type": "new_api_error",
    "code": ""
  }
}

Codes d'état et actions

Status	Signification	Action de candidature
400	Requête, modèle, champ ou paramètre non pris en charge non valide.	Corrigez la demande. Ne réessayez pas le même corps inchangé.
401	Clé API manquante, mal formée, expirée, désactivée ou invalide.	Corrigez ou faites pivoter la clé. Ne réessayez pas automatiquement.
403	Le compte, la clé, l'adresse IP, le groupe ou le modèle ne sont pas autorisés.	Examinez les contrôles d’accès et la disponibilité des modèles.
402	Le solde ou le quota est insuffisant.	Vérifiez le portefeuille et le quota de clés avant d'envoyer d'autres demandes.
404	Point de terminaison ou ressource de modèle introuvable.	Vérifiez l'URL de base, le chemin du point de terminaison et l'identifiant exact du modèle.
429	Le taux de requêtes ou la simultanéité actuelle sont trop élevés.	Reculez avec la gigue et réduisez la simultanéité.
5xx	Défaillance de la plateforme ou du fournisseur en amont.	Réessayez les requêtes sécurisées avec une limite de tentatives stricte ; conserver l’ID de la demande.

Utiliser un recul exponentiel limité

Réessayez uniquement les erreurs susceptibles d'être transitoires : échecs de connexion, HTTP 429 et réponses 5xx sélectionnées. Ajoutez une gigue aléatoire pour que de nombreux travailleurs ne réessayent pas en même temps. Définissez à la fois un nombre maximum de tentatives et un délai global.

const delaysMs = [500, 1000, 2000]

for (let attempt = 0; attempt <= delaysMs.length; attempt++) {
  try {
    return await callHippoAPI()
  } catch (error) {
    const status = error?.status
    const retryable = status === 429 || (status >= 500 && status < 600)
    if (!retryable || attempt === delaysMs.length) throw error
    const jitter = Math.floor(Math.random() * 250)
    await new Promise((resolve) => setTimeout(resolve, delaysMs[attempt] + jitter))
  }
}

Enregistrez les preuves sans enregistrer les secrets

N'enregistrez pas les en-têtes Authorization, les clés API complètes ou les invites complètes contenant des données personnelles, confidentielles ou réglementées. Rédigez avant de transmettre les erreurs aux outils d’observabilité.

Horodatage UTC et ID de trace d’application.
ID de requête HippoAPI lorsqu'il est présent.
Méthode HTTP et chemin du point de terminaison.
Identifiant du modèle, code d’état, durée et nouvelle tentative.
Un résumé des erreurs rédigé.

Avant de contacter le support

Reproduisez le problème avec la plus petite requête sécurisée, confirmez que le modèle apparaît dans GET /v1/models et vérifiez les journaux d'utilisation. Fournissez ensuite l'horodatage, le point de terminaison, le modèle, le statut HTTP, l'ID de la demande et un résumé de la demande rédigé à [email protected].

N'incluez pas votre clé API. Si vous l'avez déjà partagé ou exposé, révoquez-le avant de poursuivre l'enquête.