Gestion des codes d’erreur de l’API

Lorsque vous intégrez l’API de Cord, il est utile de bien gérer les réponses en erreur pour offrir une bonne expérience.

Structure d’une erreur

Les réponses en erreur renvoient un objet JSON plat avec deux champs :

{
  "error": "Company name is required",
  "code": "invalid_request"
}

• error : message lisible que vous pouvez afficher ou journaliser.
• code : identifiant stable sur lequel brancher votre logique (p. ex. invalid_json, invalid_request).

Codes HTTP fréquents

• 400 Bad Request : un paramètre manque ou le JSON est mal formé (code: "invalid_request" ou "invalid_json").
• 401 Unauthorized : votre clé API est invalide ou révoquée, ou vous n’avez pas envoyé l’en-tête Authorization ("invalid_key", "missing_key"), ou la clé a expiré ("key_expired").
• 402 Payment Required : votre abonnement a atteint le nombre de clés API incluses dans l’offre ("subscription_key_limit") ; révoquez une ancienne clé ou passez à une offre supérieure.
• 403 Forbidden : votre clé n’a pas la portée nécessaire (p. ex. vous utilisez une clé en lecture seule pour un POST, code "insufficient_scope"), une clé restreinte n’a pas le droit d’accéder à cette ressource ("insufficient_permissions"), la clé a des IP autorisées et la requête provient d’une autre ("ip_not_allowed"), ou une clé publiable est utilisée depuis une origine ou un domaine non autorisé ("unauthorized_origin", "missing_origin").
• 404 Not Found : la ressource n’existe pas ou n’appartient pas à votre organisation.
• 409 Conflict : l’action ne correspond pas à l’état actuel de la ressource — par exemple, annuler une facture qui a déjà des paiements imputés renvoie 409 avec code: "credit_note_required" : le document approprié est un avoir.
• 413/415 : le corps de la requête dépasse la taille maximale ("payload_too_large") ou n’est pas envoyé en application/json ("unsupported_media_type").
• 429 Too Many Requests : vous avez dépassé la limite de requêtes ou le quota mensuel de votre offre ("api_quota_exceeded"). Voir Limites de requêtes.
• 500 Internal Server Error : erreur de notre côté (rare ; contactez le support si elle persiste).
• 502/503 : le fournisseur externe dont dépend l’opération n’a pas répondu — par exemple, timbrer une facture sans pouvoir justifier le taux de change renvoie 503 avec code: "fx_unavailable" au lieu d’inventer un taux (voir la politique de taux de change dans la documentation de facturation).

Remarque : l’API v1 ne traite pas directement les paiements par carte ; ils ont lieu sur le lien public de Cord. C’est pourquoi vous ne verrez pas d’erreurs de carte refusée dans ces réponses.