Erreurs

Une erreur répond avec un statut HTTP 4xx ou 5xx et une enveloppe stable. Basez votre code sur error.code ; error.message est un texte lisible qui peut évoluer.

Exemple

HTTP/1.1 400 Bad Request
{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "details": { "fields": [{ "field": "amount", "messages": ["amount must be an integer amount in minor units (no decimals) …"] }] }
  },
  "requestId": "…"
}

Que réessayer ?

429 et 503 PROVIDER_UNAVAILABLE : réessayez après un délai. Une coupure réseau ou un 504 sur une opération d’argent : renvoyez la même requête avec la même Idempotency-Key, ou relisez la ressource. Les autres 4xx : corrigez la requête, la renvoyer telle quelle donnera la même erreur.

Requête

Statut	Code	Signification
400	`VALIDATION_ERROR`	Champ manquant, mal formé ou inconnu. Détail dans error.details.fields (champ et règles enfreintes).
400	`INVALID_JSON`	Corps qui n’est pas du JSON valide.
400	`INVALID_IDEMPOTENCY_KEY`	En-tête Idempotency-Key absent ou mal formé.
422	`INVALID_CURSOR`	Curseur de pagination invalide : repartez de la première page.
404	`NOT_FOUND, *_NOT_FOUND`	Ressource inexistante, ou d’un autre marchand (même réponse).
413	`PAYLOAD_TOO_LARGE`	Corps de plus de 256 Ko.
429	`RATE_LIMIT_EXCEEDED`	Trop de requêtes : attendez Retry-After secondes.

Authentification et droits

Statut	Code	Signification
401	`UNAUTHENTICATED`	Aucune clé fournie.
401	`INVALID_API_KEY`	Clé inconnue, révoquée, expirée ou d’un autre environnement.
403	`FORBIDDEN`	Permission absente sur la clé.
403	`MFA_REQUIRED`	Tableau de bord : l’action exige une double authentification récente.
403	`MERCHANT_SUSPENDED`	Compte suspendu.
403	`MERCHANT_NOT_ACTIVE`	Production : compte pas encore activé (dossier KYB, fournisseur).
403	`TRANSACTION_BLOCKED`	Opération bloquée par les contrôles de risque.

Règles métier

Statut	Code	Signification
409	`IDEMPOTENCY_KEY_REUSED`	Même Idempotency-Key, corps différent.
409	`IDEMPOTENCY_REQUEST_IN_PROGRESS`	Première requête encore en cours : réessayez avec la même clé après Retry-After.
409	`INVALID_STATE_TRANSITION`	Action impossible dans l’état actuel (annuler un paiement réussi…).
409	`PAYMENT_NOT_REFUNDABLE`	Paiement non remboursable, ou déjà remboursé en totalité.
409	`CUSTOMER_ALREADY_EXISTS`	Un client existe déjà avec ce téléphone.
422	`LIMIT_EXCEEDED`	Au-delà de vos limites (par opération, par jour ou par mois).
422	`INSUFFICIENT_BALANCE`	Solde insuffisant pour réserver le remboursement ou le versement.
422	`REFUND_LIMIT_EXCEEDED, PAYOUT_LIMIT_EXCEEDED`	Au-delà de vos plafonds de remboursement ou de versement.
422	`FEE_PLAN_NOT_CONFIGURED`	Aucune grille tarifaire attribuée à votre compte : contactez Galsen Pay.
422	`FEE_EXCEEDS_AMOUNT`	Les frais dépassent le montant.
422	`PROVIDER_CAPABILITY_REQUIRED`	Opération non ouverte pour ce fournisseur ou votre compte (versements, remboursement partiel…).

Fournisseurs

Statut	Code	Signification
422	`PROVIDER_REJECTED`	Le fournisseur a refusé l’opération.
501	`PROVIDER_DOCUMENTATION_REQUIRED`	Fournisseur pas encore disponible (Orange Money).
503	`PROVIDER_UNAVAILABLE`	Le fournisseur ne répond pas : rien n’a été envoyé, vous pouvez réessayer.
504	`PROVIDER_TIMEOUT`	Le fournisseur n’a pas répondu à temps : l’issue est inconnue. Relisez la ressource avant toute nouvelle action.
500	`INTERNAL_ERROR`	Erreur de Galsen Pay. Donnez le requestId au support.