Codes d'erreur

Toute erreur API renvoie la même enveloppe :

{
  "error": {
    "code": "payment_rejected",
    "message": "The selected currency is invalid.",
    "documentation_url": "https://app.so-amtar.com/docs/errors#payment_rejected"
  }
}

Code HTTP	Sens
400	Requête malformée (header invalide, JSON invalide)
401	Authentification (clé absente, invalide ou révoquée)
403	Autorisation (scope insuffisant)
404	Ressource introuvable pour ce marchand
409	Conflit (idempotence, requête en cours)
422	Validation métier (limite dépassée, état incohérent)
429	Limite de débit
500	Erreur interne (à signaler au support)
502	Orange Money indisponible en aval

Liste complète

Authentification

• missing_credentials — header Authorization absent
• invalid_api_key — clé inconnue, révoquée ou expirée, ou IP hors liste blanche
• scope_insufficient — clé sans le scope requis pour cette route (par ex. can_refund pour POST/v1/refunds)

Signature des requêtes (optionnelle)

Voir Authentification → Signature des requêtes.

• invalid_timestamp (400) — Soamtar-Timestamp à plus de 300 s de l'horloge SOAMTAR
• invalid_signature — Soamtar-Signature ne commence pas par v1= (400), ou ne correspond pas quand l'application stricte est activée (401)

Idempotence

• idempotency_key_too_long — plus de 255 caractères
• idempotency_conflict — même clé avec un corps différent, OU requête encore en cours

Paiements

• payment_rejected — validation métier (provider, devise, précision du montant, limite, KYC)
• gateway_error — Orange Money a refusé de démarrer le paiement (502)
• transaction_not_found — identifiant ou référence inconnu pour ce marchand (ou créé dans l'autre mode)

Remboursements

Voir Remboursements.

• transaction_not_found (404) — id ou référence de paiement inconnu pour ce marchand
• refunds_disabled (422) — les remboursements ne sont pas activés sur votre compte
• refund_environment_mismatch (422) — clé de test sur un paiement live, ou l'inverse
• transaction_not_refundable (422) — le paiement n'est ni success ni partially_refunded
• non_payment_transaction_refund (422) — seuls les paiements peuvent être remboursés
• provider_refund_unsupported (422) — le moyen de paiement ne prend pas en charge les remboursements
• refund_payer_phone_missing (422) — le paiement n'a pas de numéro de payeur à créditer
• amount_must_be_positive (422) — amount nul ou négatif
• transaction_already_fully_refunded (422) — plus rien à rembourser
• refund_exceeds_refundable (422) — amount supérieur au montant restant remboursable
• refund_rejected (422) — le remboursement n'a pas pu être créé
• scope_insufficient (403) — la clé n'a pas le scope can_refund
• refund_not_found (404) — id ou référence de remboursement inconnu

Webhooks

• no_webhook_endpoints (400) — POST/v1/webhooks/test sans aucun endpoint actif

Paiements sortants

• payout_not_allowed_in_test_mode — les paiements sortants exigent une clé live (sk_live_…)

Splits

• split_rejected — total supérieur au montant de la transaction, bénéficiaire inactif, transaction finale

Que faire selon le code

Code	Action recommandée
4xx (validation)	Corriger la requête, utiliser une nouvelle Idempotency-Key
401	Vérifier la clé. Ne pas réessayer.
409	Vérifier votre logique d'idempotence
429	Attendre le Retry-After, puis réessayer
5xx	Réessayer avec la même Idempotency-Key, backoff exponentiel
502	Orange Money en aval — réessayer après quelques secondes

Signaler un bug

Écrivez à support@so-amtar.com avec :

• le code d'erreur
• le documentation_url
• l'horodatage exact (UTC)
• votre merchant_ref ou l'id SOAMTAR
• le header X-Request-Id de la réponse (si présent)