Gestion des erreurs
L'API utilise des codes de réponse HTTP conventionnels pour indiquer le succès ou l'échec des requêtes. Cette page documente les formats d'erreur et les stratégies de gestion.
Format de réponse d'erreur
Toutes les réponses d'erreur suivent une structure JSON cohérente :
{
"error": "VALIDATION_ERROR",
"message": "Invalid request parameters",
"timestamp": "2026-07-10T12:00:00Z",
"path": "/api/v1/assets",
"details": [{ "field": "size", "message": "must be at most 100" }]
}| Champ | Description |
|---|---|
| error | Code d'erreur lisible par machine |
| message | Description de l'erreur lisible par l'homme |
| timestamp | Quand l'erreur s'est produite |
| path | Le chemin du point d'accès demandé |
| details | Détails supplémentaires pour les erreurs de validation (facultatif) |
Codes de statut HTTP
| Code | Description |
|---|---|
| 400 | Paramètres de requête invalides ou corps de requête malformé |
| 401 | Clé d'API manquante ou invalide |
| 403 | La clé d'API n'a pas les autorisations requises pour ce point de terminaison |
| 404 | La ressource demandée n'existe pas |
| 429 | Limite de débit dépassée - réessayez après le temps spécifié |
| 500 | Erreur interne du serveur - veuillez contacter le support si le problème persiste |
| 503 | Service temporairement indisponible - veuillez réessayer plus tard |
Stratégie de nouvelle tentative
Pour les erreurs transitoires, implémentez une stratégie de nouvelle tentative avec une backoff exponentielle :
- Pour les erreurs 429, attendez le temps spécifié dans l'en-tête X-RateLimit-Reset avant de réessayer
- Pour les erreurs 5xx, utilisez une backoff exponentielle (1s, 2s, 4s, 8s...) avec jitter
- Définissez un nombre maximum de nouvelles tentatives (par exemple, 3 à 5 tentatives) pour éviter les boucles infinies
Limitation du taux
Lorsque vous dépassez la limite de taux, l'API renvoie un code d'état 429 avec des détails sur le moment où vous pouvez réessayer :
Utilisez le champ retryAfter ou l'en-tête X-RateLimit-Reset pour déterminer quand réessayer votre requête.
Erreurs de validation
Pour les erreurs 400, la réponse inclut un tableau details avec des erreurs spécifiques au niveau des champs :
Bonnes pratiques de gestion des erreurs
- Vérifiez toujours le code d'état HTTP avant d'analyser le corps de la réponse
- Implémentez une décrémentation exponentielle pour les erreurs 429 et 5xx
- Enregistrez les erreurs avec l'horodatage et le chemin pour le débogage
- Traiter les codes d'erreur spécifiques différemment (par exemple, 401 déclenche une réauthentification)