Erreurs, quotas et nouvelles tentatives
Interpréter les erreurs Orbit, respecter les quotas et réessayer sans amplifier une panne.
Enveloppe d’erreur
Les erreurs produites par Orbit utilisent une enveloppe stable :
{
"error": {
"code": "invalid_category",
"message": "Le paramètre category doit valoir games, movies, anime, series, music ou books.",
"requestId": "00000000-0000-0000-0000-000000000000"
}
}Conservez X-Request-Id ou error.requestId pour le diagnostic. Ne transmettez jamais une clé, un en-tête complet, une URL avec des paramètres sensibles ou le corps de la requête.
Statuts et codes
| HTTP | Codes possibles | Action client |
|---|---|---|
400 | invalid_query, invalid_category, invalid_limit, invalid_json, invalid_ids | Corriger la requête, sans nouvelle tentative automatique. |
401 | missing_orbit_api_key, invalid_orbit_api_key | Vérifier l’environnement et la clé Orbit, sans nouvelle tentative automatique. |
403 | insufficient_scope | Demander la permission requise, sans nouvelle tentative automatique. |
404 | route_not_found | Corriger la route. Un UUID inconnu reste un résultat 200/not_found. |
405 | method_not_allowed | Utiliser la méthode indiquée par Allow. |
413 | payload_too_large | Réduire le corps à 32 KiB maximum. |
415 | unsupported_media_type | Envoyer Content-Type: application/json. |
429 | rate_limit_exceeded, monthly_quota_exceeded | Attendre la durée de Retry-After, puis réessayer. |
500 | internal_error | Réessayer avec une attente exponentielle bornée. |
503 | environment_unavailable, authentication_unavailable, usage_metering_unavailable, catalog_unavailable | Réessayer avec une attente exponentielle bornée. |
Quotas
Chaque réponse authentifiée expose les limites minute et jour UTC :
X-RateLimit-Limit
X-RateLimit-Remaining
X-RateLimit-Reset
X-Orbit-Daily-RateLimit-Limit
X-Orbit-Daily-RateLimit-Remaining
X-Orbit-Daily-RateLimit-ResetLes valeurs Reset sont des horodatages Unix en secondes. Une requête authentifiée consomme son quota avant la validation de la route ou du corps. Les clés absentes, invalides, expirées, révoquées, suspendues ou sans permission ne consomment pas de quota.
Politique de nouvelle tentative
GET /search et POST /resolve sont des lectures réessayables sans effet de bord. Appliquez ces règles :
- Ne réessayez jamais automatiquement un
400,401,403,404,405,413ou415. - Pour
429, attendez au minimumRetry-Aftersecondes. - Pour
500,503, une erreur réseau ou un délai dépassé, utilisez une attente exponentielle avec une petite variation aléatoire. - Bornez le nombre de tentatives et le temps total selon le budget de latence de votre service.
- Ne lancez pas de nouvelles tentatives parallèles et ne contournez jamais un quota avec plusieurs clés.
Exemple de délais avant variation aléatoire : 250 ms, 500 ms, puis 1 s. Cette recommandation client ne constitue pas un engagement de service.