Erreurs

Format d'une erreur

Une erreur répond au format application/problem+json (RFC 9457), avec un code stable :

{
  "type": "https://mabellenote.com/developers/errors#invalid_request",
  "title": "Invalid request",
  "status": 400,
  "code": "invalid_request",
  "detail": "The request contains invalid fields.",
  "requestId": "req_Qm9uam91ciBNYSBCZWxsZQ",
  "errors": [{ "path": "query.limit", "message": "Must be less than or equal to 100" }]
}

Chaque réponse, erreur ou non, porte l'en-tête X-Request-Id. Communiquez-le au support pour toute question sur un appel précis.

Traiter une erreur

• Programmez sur code, jamais sur title ni sur detail, dont le texte peut évoluer.
• Un code ne disparaît pas et ne change pas de statut dans une version. De nouveaux codes peuvent apparaître avec de nouvelles opérations : traitez un code inconnu d'après son statut HTTP.
• 429 rate_limited : attendez le nombre de secondes indiqué par l'en-tête Retry-After, puis renvoyez la requête.
• 409 idempotency_in_progress : une requête avec la même Idempotency-Key est encore en cours. Renvoyez-la un peu plus tard, avec la même clé. Le guide d'idempotence détaille ces cas.
• 503 service_unavailable : la requête n'a eu aucun effet. Renvoyez-la après le délai de Retry-After quand il est présent, sinon après une attente croissante.
• 500 internal_error : renvoyez la requête avec une attente croissante et un nombre d'essais limité, puis contactez le support avec le requestId.
• Les autres erreurs 4xx ne se corrigent pas en renvoyant la même requête : corrigez-la d'abord.
• 404 route_not_found signale un chemin qui n'existe pas, 404 not_found une ressource absente ou appartenant à un autre compte. 405 method_not_allowed liste les méthodes acceptées dans l'en-tête Allow.

Catalogue des codes

Cette liste est tirée de la description OpenAPI de l'API. Elle fait partie du contrat de la version v1.