Format de réponse

Toute erreur (4xx ou 5xx) suit ce format JSON :
Champs :
  • statusCode : code HTTP (200-599)
  • message : message humain décrivant l’erreur
  • code : code machine stable, présent sur une partie des erreurs (voir le tableau ci-dessous). Quand il est présent, branchez votre logique dessus.
Beaucoup d’erreurs 4xx n’ont pas de champ code (clé manquante, invalide ou expirée, KYB requis, IP non autorisée…) : elles sont identifiées par leur statusCode et leur message texte. Le 429 (rate limit) est une exception : son corps a une forme distincte, détaillée dans Rate limits.

Codes machine

Les codes ci-dessous sont les seuls codes machine stables émis par l’API marchande. Tous les autres cas d’erreur 4xx sont signalés par statusCode + message, sans champ code.
Les rejets liés à la double authentification (par exemple si le propriétaire de la clé a désactivé sa 2FA) renvoient un 403 dont le libellé reconnaissable est porté par le champ message, pas par code. Les codes 2FA du flux de connexion au dashboard ne concernent pas l’intégration par clé API.

Codes HTTP utilisés

Hiérarchie d’erreurs SDK Node

Chaque erreur du SDK descend de IziPayError. Vous pouvez catch tout d’un coup OU brancher sur la classe spécifique :
La hiérarchie typée du SDK expose des propriétés défensives comme .requestId et .fields (parsing tolérant côté client). L’API marchande actuelle ne peuple pas ces champs : ils restent undefined. Branchez votre logique sur la classe d’erreur et sur .code plutôt que sur ces propriétés.

Retry-Safe vs Non-retryable

Le SDK fait ces retry automatiquement (sauf si vous passez maxRetries: 0).

Logging recommandé

Loguez statusCode et code (quand il est présent) pour faciliter le tri de vos erreurs et les échanges avec le support.
Toutes les exceptions du SDK ont un name distinct (pas le Error générique). Votre outil d’observabilité (Sentry, Datadog) les groupera par type d’erreur grâce au name distinct, sans configuration supplémentaire.