Erreurs

Les erreurs partagent une même enveloppe (voir la vue d’ensemble). Basez votre logique sur code, journalisez meta.request_id et traitez message comme un texte en anglais destiné aux humains.

Erreurs client

Code	Statut	Signification et marche à suivre
validation_failed	400	Un champ n’a pas passé la validation. field le nomme ; details explique. Corrigez le champ.
bad_request	400	La requête n’a pas pu être lue du tout : JSON mal formé, flux Content-Encoding corrompu, corps interrompu. Aucun champ à corriger ; vérifiez le transport.
validation_error	400	X-Account-Id a été envoyé à un endpoint qui l’interdit (/auth/login, /auth/refresh, /auth/swap-company, /auth/logout).
cursor_expired	400	Le curseur de pagination date de plus de 24 heures. Recommencez la liste.
unauthenticated	401	Jeton manquant ou invalide. Rafraîchissez la session ou vérifiez la clé.
invalid_signature	401	La signature d’un webhook n’a pas pu être vérifiée. Voir Webhooks.
forbidden	403	Le jeton est valide mais n’a pas la permission.
account_context_mismatch	403	X-Account-Id ne correspond pas au compte du jeton. L’idée que le client se fait de l’entreprise courante a dérivé ; relisez-la depuis la session.
not_found	404	La ressource n’existe pas ou appartient à un autre compte ou site. L’API ne distingue jamais les deux cas.
conflict	409	Conflit d’état : verrou optimiste, contrainte d’unicité ou action interdite dans l’état actuel (par exemple écrire dans une conversation fusionnée).
idempotency_key_conflict	409	La Idempotency-Key a été réutilisée avec un corps différent.
payload_too_large	413	Le corps dépasse la limite de cette famille d’endpoints.
unsupported_media_type	415	Content-Type incorrect.
unprocessable	422	JSON valide, mais refusé par une règle métier (par exemple un créneau de réservation hors des horaires d’ouverture).
storage_quota_exceeded	422	Le compte a atteint la limite de stockage de son forfait. details contient used_bytes, quota_bytes et requested_bytes ; libérez de l’espace ou passez à un forfait supérieur.
rate_limited	429	Ralentissez. Respectez Retry-After et details.retry_after_seconds.

Erreurs serveur

Code	Statut	Signification et marche à suivre
internal_error	500	Échec inattendu. Réessayez une fois, puis contactez le support avec le request_id.
upstream_unavailable	502	La passerelle n’a pas pu joindre le service. Une nouvelle tentative rapide réussit généralement.
service_unavailable	503	Maintenance planifiée ou disjoncteur ouvert. Réessayez après le délai indiqué par l’en-tête Retry-After.
ai_vendor_out_of_funds	503	Votre fournisseur d’IA a refusé l’appel pour des raisons de facturation (un 402 ou un 429 de quota renvoyé par le fournisseur). Rechargez le compte chez le fournisseur ; réessayer ne servira à rien.
upstream_timeout	504	Le service n’a pas répondu à temps. Réessayez lorsque retry_after est présent.

Nouvelles tentatives

Réessayez les 429, 502, 503, 504 et les échecs réseau avec une temporisation exponentielle, et renvoyez la même Idempotency-Key lors de la nouvelle tentative pour qu’une écriture ne soit jamais appliquée deux fois. Ne réessayez pas les 4xx autres que 429.