Erreurs
La forme
Chaque échec renvoie application/problem+json, conformément à la
RFC 9457. Le statut HTTP vous indique
la classe du problème ; code vous dit exactement lequel.
HTTP/1.1 422 Unprocessable Content
Content-Type: application/problem+json
X-Request-Id: req_4b81f0c9
{
"type": "https://skautik.com/docs/developers/errors#validation_failed",
"title": "Validation failed",
"status": 422,
"code": "validation_failed",
"detail": "One or more fields could not be accepted.",
"request_id": "req_4b81f0c9",
"errors": [
{
"field": "price",
"code": "out_of_range",
"detail": "Must be a positive integer in minor units."
},
{
"field": "address.country",
"code": "unknown_value",
"detail": "Expected an ISO 3166-1 alpha-2 code."
}
]
}Le tableau errors n'apparaît que sur un 422. Il nomme tous les problèmes d'un coup plutôt
que le premier : un formulaire peut donc être corrigé en une passe au lieu d'un champ par
aller-retour.
Branchez sur code plutôt que sur la prose de title ou detail. Le code est
stable ; la prose est écrite pour une personne et peut être reformulée.
Codes
| Code | Statut | Signification | Que faire |
|---|---|---|---|
authentication_required | 401 | Pas de clé, ou une clé non valide. | Corrigez l'en-tête ou la clé. Réessayer à l'identique ne réussira jamais. |
permission_denied | 403 | Clé valide, mais la portée ou la propriété de la fiche l'interdit. | Utilisez une clé avec portée d'écriture, ou cessez de modifier une fiche que vous n'avez pas publiée. |
not_found | 404 | Ressource inexistante, ou aucune que votre clé puisse voir. | Traitez-le comme une absence. Ce n'est pas un échec passager. |
conflict | 409 | Une Idempotency-Key a été réutilisée avec un corps différent. | Générez une nouvelle clé pour une création réellement nouvelle. |
managed_by_import | 409 | La fiche appartient à une source d'import, qui fait autorité sur elle. | Modifiez-la dans le système qui alimente l'import, pas ici. |
precondition_failed | 412 | Le If-Match ne correspondait pas à l'ETag actuel. | Relisez, réappliquez votre modification, réessayez une fois. |
payload_too_large | 413 | L'envoi dépasse la limite de son endpoint. | Redimensionnez avant d'envoyer. Ne réessayez pas les mêmes octets. |
unsupported_media_type | 415 | Le Content-Type est absent ou non accepté. | Envoyez application/json, ou multipart/form-data pour les envois de fichiers. |
validation_failed | 422 | Le corps a été analysé mais un champ est inacceptable. | Lisez le tableau errors ; chaque entrée nomme un champ et la raison de l'échec. |
rate_limited | 429 | Limite de rafale dépassée. Le volume mensuel ne refuse pas. | Attendez le Retry-After, puis réessayez avec un décalage aléatoire. |
internal_error | 500 | Une panne de notre côté. | Réessayez avec une temporisation exponentielle. Citez le request_id si cela persiste. |
service_unavailable | 503 | Temporairement incapable de servir, généralement pendant un déploiement. | Réessayez avec temporisation. Cela se résout généralement en quelques secondes. |
Que réessayer
La règle est simple, et s'y tromper est la façon la plus courante dont une intégration transforme une petite panne en une grande.
- 4xx : ne réessayez pas, sauf s'il s'agit d'un 429. La requête est mauvaise, et la répéter la laissera mauvaise. Les exceptions sont le 429 et le 412, que l'on réessaie une fois après relecture.
- 5xx : réessayez avec temporisation exponentielle et décalage aléatoire, dans un budget borné. Jamais en boucle serrée : un service en difficulté se rétablit d'autant plus lentement qu'on le pousse.
- Les délais dépassés sont ambigus. Une requête expirée peut tout de même avoir été appliquée. C'est exactement à cela que servent les clés d'idempotence sur les écritures.
Signaler un problème
Citez le request_id quand vous écrivez à
support@skautik.com. Avec lui nous pouvons retrouver la requête
exacte ; sans lui, la première chose que nous demanderons est une reproduction. Journalisez
l'en-tête sur chaque appel échoué afin de l'avoir sous la main le moment venu.