​
Format de réponse

Toute erreur (4xx ou 5xx) suit ce format JSON : 
{
  "statusCode": 403,
  "message": "La clé n'a pas le scope requis pour cette opération",
  "code": "INSUFFICIENT_SCOPE"
}
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.
CodeHTTPSens
INSUFFICIENT_SCOPE403La clé n’a pas le scope requis pour cette opération
DASHBOARD_ONLY403Opération réservée au dashboard (indisponible par API)
OWNER_ONLY403Opération réservée au propriétaire du compte
DESTINATION_NOT_MATURED403Adresse de la liste d’autorisation encore en cours de maturation
ACCOUNT_FROZEN401Compte gelé
USER_SUSPENDED401Membre suspendu
CREDENTIALS_CHANGED401Identifiants modifiés, reconnectez-vous
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

CodeSens
200/201Succès
204Succès sans body (ex: delete)
400Bad Request : JSON malformé, headers manquants
401Unauthorized : clé manquante, invalide ou expirée
403Forbidden : scope insuffisant, KYB requis, IP non autorisée
404Not Found
409Conflict : ressource déjà existante (ex: slug déjà utilisé)
422Unprocessable Entity : validation métier
429Too Many Requests : rate limit (voir Rate limits)
5xxErreur serveur : retryable

​
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 : 
import {
  IziPayError,                  // base
  IziPayApiError,               // 4xx/5xx
    IziPayAuthError,            // 401/403
    IziPayNotFoundError,        // 404
    IziPayValidationError,      // 422
    IziPayRateLimitError,       // 429 — .retryAfter
    IziPayServerError,          // 5xx
  IziPayNetworkError,           // pas de réponse (DNS, timeout)
  IziPayWebhookError,           // signature invalide
} from 'izichangepay-sdk';

try {
  await izipay.payouts.create({ /* ... */ });
} catch (err) {
  if (err instanceof IziPayValidationError) {
    console.error('Invalid input:', err.message);
  } else if (err instanceof IziPayRateLimitError) {
    console.error(`Wait ${err.retryAfter}s and retry`);
  } else if (err instanceof IziPayAuthError) {
    // Révoquer le token côté votre app, demander re-login
  } else if (err instanceof IziPayError) {
    console.error('IzichangePay:', err.message);
  } else {
    throw err; // pas notre erreur
  }
}
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

ErreurRetry ?
IziPayNetworkError✅ Oui, exponentiel
IziPayServerError (5xx)✅ Oui
IziPayRateLimitError (429)✅ Oui, après retryAfter
IziPayValidationError (422)❌ Non, fixez le payload
IziPayAuthError (401/403)❌ Non, la clé est invalide / révoquée
IziPayNotFoundError (404)❌ Non
IziPayApiError 409❌ Non, conflit de ressource (ex: slug déjà utilisé)
Le SDK fait ces retry automatiquement (sauf si vous passez maxRetries: 0).

​
Logging recommandé

try {
  await izipay.paymentIntents.create({ /* ... */ });
} catch (err) {
  if (err instanceof IziPayError) {
    logger.error({
      sdk: 'izipay',
      class: err.name,
      message: err.message,
      ...(err instanceof IziPayApiError && {
        statusCode: err.statusCode,
        code: err.code,
      }),
    });
  }
  throw err;
}
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.