Erreurs

Toutes les erreurs SandPay suivent un format unique et stable. Pas de surprise, pas de format ad hoc selon l’endpoint.

Format de réponse

{
  "error": "invalid_body",
  "message": "amount must be greater than 0",
  "detail": {
    "fieldErrors": {
      "amount": ["Number must be greater than 0"]
    }
  }
}

error — code machine, stable, à utiliser dans votre logique (switch, if).
message — texte humain, en anglais, susceptible d’évoluer.
detail — payload structuré optionnel (erreurs Zod par champ, contexte additionnel).

L’en-tête X-Request-Id accompagne chaque réponse (succès comme erreur). Conservez-le si vous ouvrez un ticket support.

Codes par statut HTTP

Status	`error`	Quand
400	`invalid_body`	Le corps JSON ne valide pas le schéma (Zod). `detail` contient les champs en faute.
400	`invalid_params`	Paramètres de query invalides (par ex. `limit=999`).
401	`unauthorized`	En-tête `Authorization` absent.
401	`invalid_api_key`	Clé inconnue, révoquée ou mal formée.
402	`quota_exceeded`	Quota mensuel atteint sur le plan courant. Mettez à niveau.
404	`not_found`	Ressource introuvable (transaction, application, client…).
404	`env_not_found`	Le couple `country`/`operator` n’a pas d’environnement configuré.
429	`rate_limited`	Trop de requêtes — retry après l’en-tête `Retry-After`.
5xx	`internal`	Erreur côté SandPay. Tracée dans Sentry, retry recommandé.

Stratégie de retry

Status	Retriable ?	Comment
4xx (sauf 429)	Non	Corrigez la requête. Réessayer ne changera rien.
429	Oui	Respectez `Retry-After`, puis backoff exponentiel.
5xx	Oui	Backoff exponentiel : 1s, 2s, 4s, 8s, 16s. Max 5 essais.

Le SDK Node lève une SandPayApiError qui expose status, code, message, detail et requestId — utilisez-la pour brancher votre logique de retry.

Exemple — gérer un quota dépassé

import { SandPay, SandPayApiError } from "@drwintech/sandpay";

const sp = new SandPay({ apiKey: process.env.SANDPAY_API_KEY! });

try {
  await sp.payments.create({ /* ... */ });
} catch (err) {
  if (err instanceof SandPayApiError && err.code === "quota_exceeded") {
    // Notifier l'équipe, déclencher l'upgrade, etc.
    notifyOps("SandPay quota dépassé, requestId=" + err.requestId);
    return;
  }
  throw err;
}

Démarrer

Concepts

Intégration

Guides opérateurs

SDKs

Référence API

Format de réponse

Codes par statut HTTP

Stratégie de retry

Exemple — gérer un quota dépassé

​Format de réponse

​Codes par statut HTTP

​Stratégie de retry

​Exemple — gérer un quota dépassé

Format de réponse

Codes par statut HTTP

Stratégie de retry

Exemple — gérer un quota dépassé