Erreurs et limites

Toutes les erreurs de l'API ont la même forme, et un code stable sur lequel votre code peut brancher. Le message, lui, peut être reformulé — ne l'analysez jamais.

Le format

Les erreurs suivent la RFC 7807 et arrivent en application/problem+json :

{
  "type": "https://partnercut.fr/docs/errors/request.invalid",
  "title": "Données invalides",
  "status": 422,
  "code": "request.invalid",
  "detail": "Les données envoyées sont invalides.",
  "violations": {
    "amountCents": "Cette valeur doit être un entier."
  }
}

Branchez sur code, jamais sur detail. Le code ne change pas ; le message est là pour être lu par un humain, et il peut être reformulé ou traduit sans préavis.

Les codes

Code	HTTP	Quand	Que faire
request.invalid	422	Le corps ne passe pas la validation. Le champ `violations` nomme chaque champ fautif.	Corrigez et renvoyez. Un rejeu à l'identique échouera pareil.
auth.failed	401	Clé absente, inconnue, révoquée — ou signature invalide.	Vérifiez l'en-tête, puis la clé dans le CRM. Ne réessayez pas en boucle.
access.forbidden	403	La clé est valide mais n'a pas la portée nécessaire.	Émettez une clé avec la portée manquante. Le message la nomme.
resource.not_found	404	La ressource n'existe pas — ou n'appartient pas au projet de la clé.	Les deux cas rendent la même réponse, volontairement : distinguer permettrait d'explorer ce qui appartient à d'autres.
resource.conflict	409	L'état actuel interdit l'opération : ressource déjà créée, action déjà faite.	Relisez l'état avant de réessayer. Un rejeu ne débloquera rien.
rate_limit.exceeded	429	Quota d'appels dépassé pour cette clé.	Attendez le délai de l'en-tête `Retry-After`. Réessayer aussitôt aggrave la situation.
server.error	500	Un défaut chez nous. La réponse porte un identifiant de corrélation.	Rejouez plus tard — vos appels sont idempotents — et citez cet identifiant au support.

Ce qui n'est PAS une erreur

Trois situations ressemblent à des échecs et n'en sont pas. Les traiter comme telles est la faute la plus fréquente en intégration :

Un 200 sur POST /events. Ce n'est pas un problème, c'est un rejeu : cet identifiant existait déjà, et la même commission vous est rendue. Le 201 signale la première écriture.
Un rattachement refusé. POST /customers/attribute répond 200 avec attributed: false quand le code est inconnu. Un ?ref= périmé ne doit pas casser une inscription.
Une commission à zéro. Le revenu est enregistré, mais rien n'était commissionnable — client non rattaché, rente échue, aucune règle. Le champ warnings dit laquelle de ces raisons s'applique.

Réessayer, sans faire de dégâts

Les écritures de revenu sont idempotentes : le même externalId ne produit qu'une commission, quel que soit le nombre de tentatives. Vous pouvez donc rejouer une file entière après un incident sans rien comparer.

Rejouez sur 429, 500 et les erreurs réseau, avec un délai qui double à chaque tentative. Ne rejouez jamais un 422 ni un 403 : ils échoueront à l'identique, et vous n'y gagnerez qu'un quota consommé.