Guides
Erreurs et récupération
Utiliser les codes d’erreur stables, les détails structurés et les identifiants de requête pour savoir quoi corriger et quand réessayer.
Une enveloppe d’erreur cohérente
Une erreur contient un objet error avec type, code, message, request_id et éventuellement details. Basez la logique sur le statut HTTP et le code stable ; le message sert au diagnostic. Chaque réponse contient aussi X-Request-Id. Conservez cet identifiant pour signaler un problème, sans journaliser les clés ni les payloads sensibles.
{
"error": {
"type": "validation_error",
"code": "validation_failed",
"message": "The supplied field is not available.",
"details": { "unknown": ["nname"], "nearest": { "nname": ["name"] } },
"request_id": "4d85a25f-d510-41f5-b228-32a875670fd0"
}
}Choisir la bonne récupération
Corrigez les entrées invalides et problèmes d’accès avant de réessayer. Un 404 couvre aussi une fiche d’un autre espace ou invisible au propriétaire.
| Statut | Codes | Action |
|---|---|---|
| 400 | invalid_request | Corrigez JSON, paramètres, filtres ou curseur. |
| 401 | invalid_api_key, expired_api_key, key_assurance_stale | Vérifiez secret, expiration et MFA ; remplacez la clé si nécessaire. |
| 403 | ip_not_allowed, permission_denied, plan_upgrade_required, insufficient_scope, feature_unavailable, forbidden | Vérifiez IP serveur, appartenance, rôle, offre, périmètre et disponibilité. |
| 404 | not_found, unknown_resource, route_not_found | Vérifiez chemin, identifiants et visibilité du propriétaire. |
| 405 | method_not_allowed | Utilisez une méthode de l’en-tête Allow ; certaines ressources sont en lecture seule. |
| 409 | conflict, idempotency_key_in_use | Résolvez le conflit ou attendez avant la même requête idempotente. |
| 413 | payload_too_large | Réduisez le corps à 1 MiB maximum. |
| 422 | validation_failed, idempotency_key_reused | Corrigez champs/types ou utilisez une nouvelle clé pour une autre opération. |
| 429 | rate_limited, quota_exceeded | Respectez Retry-After ; consultez limites et réinitialisation du quota. |
| 500 / 503 | internal_error, service_unavailable | Réessayez avec une temporisation limitée et la même clé d’idempotence. |
Utiliser les détails
Les détails de validation peuvent inclure unknown, nearest et alternatives, avec les champs ou options à corriger. La pagination peut inclure max_page ; le quota, resets_at ; la validation de la base, sqlstate et un hint pertinent. Décrivez à nouveau la ressource si le schéma de l’espace a changé.
Limiter les tentatives
Pour les échecs temporaires, limitez le nombre de tentatives avec une temporisation exponentielle et aléatoire. Respectez Retry-After lorsqu’il est présent. Ne réessayez pas automatiquement un 400, 401, 403 ou un échec de validation. Conservez requête exacte et clé d’idempotence lors d’une écriture, puis vérifiez les résultats incertains avant une nouvelle opération.