Erreurs

Comprenez le format d’erreur stable et les codes renvoyés par l’API YAOKA.

Format commun

Les erreurs utilisent toujours la même enveloppe. field est présent lorsqu’un champ précis est en cause.

{
  "error": {
    "code": "validation_error",
    "message": "Invalid request body.",
    "field": "lines",
    "requestId": "req_01J..."
  }
}

Conservez error.requestId dans vos logs applicatifs. Ne journalisez jamais la clé API ni les données sensibles du document.

HTTP	Code	Signification
`401`	`auth_required`	Aucune clé API n’a été envoyée.
`401`	`auth_invalid`	Clé invalide, expirée ou révoquée.
`401`	`auth_wrong_scope`	Clé incompatible avec le mode ou l’organisation demandée.
`403`	`insufficient_scope`	La clé ne possède pas le scope demandé.
`404`	`not_found`	Ressource absente ou inaccessible dans cette organisation.
`400`	`validation_error`	Paramètre, query ou corps invalide.
`409`	`conflict`	Conflit, notamment une réutilisation incorrecte d’une clé d’idempotence.
`409`	`business_rule_violation`	L’opération contredit l’état métier de la ressource.
`429`	`rate_limited`	Limite d’appels atteinte.
`500`	`internal_error`	Erreur interne YAOKA.
`502`	`pennylane_unreachable`	Pennylane n’a pas pu être joint.

Ne retentez pas automatiquement les erreurs 400, 401, 403, 404 ou 409 sans corriger la cause.
Pour 429, attendez le nombre de secondes indiqué dans Retry-After.
Pour 500 et 502, appliquez un backoff exponentiel avec jitter.
Pour un POST idempotent après un timeout ou une erreur serveur, réutilisez exactement la même Idempotency-Key.