Codes d’erreur

La source de vérité faisant autorité pour les métadonnées d’erreur de la plateforme est le catalogue backend dans IkawaariErrorCatalog et IkawaariPaaSDomainErrorCodes.

Cette page documente les modules d’erreur implémentés, les codes représentatifs, le comportement des statuts HTTP et les recommandations de retry.

Format d’erreur

Les surfaces API et marchandes renvoient généralement des payloads d’erreur structurés. Une forme typique est :

{
  "error": {
    "code": "IKW-PAYOUT-003",
    "message": "Description de l'erreur",
    "type": "domain_error"
  }
}

Politique de source de vérité

• Les valeurs de code proviennent de IkawaariPaaSDomainErrorCodes
• Le module, le statut HTTP et la possibilité de retry proviennent de IkawaariErrorCatalog
• Certains alias de moteurs rétrocompatibles sont également mappés dans le catalogue

Référence des statuts HTTP

Code	Signification
200	Succès
201	Créé
400	Requête invalide ou entrée invalide
401	Authentification requise ou identifiants/token invalides
402	Contrainte de balance ou de fonds
403	Interdit, politique bloquante ou mismatch marchand
404	Ressource introuvable
409	Conflit d’état, opération en doublon ou conflit d’idempotence
410	Invitation expirée ou cycle de vie de la ressource terminé
412	Précondition échouée
423	État verrouillé ou environnement/test mode déjà actif
429	Limite de débit ou cooldown de retry déclenché
500	Erreur interne de plateforme
502	Échec d’un provider amont ou de livraison webhook
503	Service temporairement indisponible
504	Timeout amont ou système

Résumé des modules

Module	Zone typique	Statuts typiques	Cas retryables
AUTH	connexion, tokens, clés API	401	non
AUTHZ	rôles, membership, scopes	403	non
ORG	accès organisation	403, 404	non
MERCHANT	état marchand et résolution de compte	403, 404, 409, 410	non
REQ	validation et idempotence	400, 409	non
RES	état générique des ressources	404, 409	non
RATE	throttling	429	oui
SYS	défaillances plateforme/système	500, 503, 504	certains
CHK	flux checkout	400, 404	non
TRANSFER	paiements et remboursements	400, 402, 404, 409, 502	échecs provider uniquement
PAYOUT	opérations de payout	400, 402, 403, 404, 409	non
BILLING	factures et plans	404, 500	erreurs de cycle uniquement
LEDGER	balance et comptabilité	400, 402, 404	non
COMPLIANCE	KYC, limites	400, 403	non
SECURITY	MFA, passkeys, challenges	400, 403, 429, 500	non
RISK	gestion de cas et règles	404, 409	non
CONFIG	feature flags et politique pays/devise	400, 403	non
PRODUCT	catalogue produit	400, 404	non
WEBHOOK	endpoints webhook et livraison	404, 502	échecs de livraison uniquement
TERMINAL	transitions reader/session	400, 409	non
EXTERNAL	intégrations provider	400, 502, 504	indisponibilité/timeout uniquement
ESCROW	contrats d’escrow et litiges	400, 403, 404, 409	non
FUNDING	campagnes de financement	400, 403, 404, 409	non
MKTPLACE	moteur marketplace	400, 403	non
APP	cycle de vie des ecosystem apps	403, 404	non
ENV	état sandbox/live test-mode	412, 423	non
CONNECT	configuration de compte connecté	400, 404	non

Authentification et autorisation

Code	Module	HTTP	Retryable	Signification
<a id="IKW-AUTH-001"></a>IKW-AUTH-001	AUTH	401	Non	Identifiants invalides
<a id="IKW-AUTH-002"></a>IKW-AUTH-002	AUTH	401	Non	Authentification requise
<a id="IKW-AUTH-003"></a>IKW-AUTH-003	AUTH	401	Non	Token révoqué
<a id="IKW-AUTH-004"></a>IKW-AUTH-004	AUTH	401	Non	Token expiré
<a id="IKW-AUTH-005"></a>IKW-AUTH-005	AUTH	401	Non	Token invalide
<a id="IKW-AUTH-006"></a>IKW-AUTH-006	AUTH	401	Non	Session expirée
<a id="IKW-AUTH-007"></a>IKW-AUTH-007	AUTH	401	Non	Session révoquée
<a id="IKW-AUTH-008"></a>IKW-AUTH-008	AUTH	401	Non	Clé API expirée
<a id="IKW-AUTH-009"></a>IKW-AUTH-009	AUTH	401	Non	Clé API tournée
<a id="IKW-AUTHZ-001"></a>IKW-AUTHZ-001	AUTHZ	403	Non	Interdit
<a id="IKW-AUTHZ-002"></a>IKW-AUTHZ-002	AUTHZ	403	Non	Rôle insuffisant
<a id="IKW-AUTHZ-003"></a>IKW-AUTHZ-003	AUTHZ	403	Non	Membership requis

Fondations marchand, requête et système

Code	Module	HTTP	Retryable	Signification
<a id="IKW-MERCHANT-001"></a>IKW-MERCHANT-001	MERCHANT	404	Non	Marchand introuvable
<a id="IKW-MERCHANT-002"></a>IKW-MERCHANT-002	MERCHANT	403	Non	Marchand désactivé
<a id="IKW-MERCHANT-003"></a>IKW-MERCHANT-003	MERCHANT	409	Non	Le marchand existe déjà
<a id="IKW-MERCHANT-004"></a>IKW-MERCHANT-004	MERCHANT	410	Non	Invitation marchand expirée
<a id="IKW-MERCHANT-005"></a>IKW-MERCHANT-005	MERCHANT	404	Non	Compte marchand introuvable
<a id="IKW-ORG-001"></a>IKW-ORG-001	ORG	403	Non	Organization Access Denied
<a id="IKW-ORG-002"></a>IKW-ORG-002	ORG	404	Non	Organization Not Found
<a id="IKW-RATE-001"></a>IKW-RATE-001	RATE	429	Oui	Trop de requêtes
<a id="IKW-REQ-001"></a>IKW-REQ-001	REQ	400	Non	Entrée invalide
<a id="IKW-REQ-002"></a>IKW-REQ-002	REQ	400	Non	Paramètre requis manquant
<a id="IKW-REQ-003"></a>IKW-REQ-003	REQ	400	Non	Paramètre invalide
<a id="IKW-REQ-004"></a>IKW-REQ-004	REQ	409	Non	Conflit d’idempotence
<a id="IKW-RES-001"></a>IKW-RES-001	RES	404	Non	Ressource introuvable
<a id="IKW-RES-002"></a>IKW-RES-002	RES	409	Non	La ressource existe déjà
<a id="IKW-RES-003"></a>IKW-RES-003	RES	409	Non	Conflit d’état de ressource
<a id="IKW-SYS-001"></a>IKW-SYS-001	SYS	500	Non	Erreur interne
<a id="IKW-SYS-002"></a>IKW-SYS-002	SYS	503	Oui	Service indisponible
<a id="IKW-SYS-003"></a>IKW-SYS-003	SYS	504	Oui	Timeout système

Checkout, paiements, remboursements et payouts

Code	Module	HTTP	Retryable	Signification
<a id="IKW-CHK-001"></a>IKW-CHK-001	CHK	400	Non	Lien de paiement invalide
<a id="IKW-CHK-002"></a>IKW-CHK-002	CHK	404	Non	Checkout session introuvable
<a id="IKW-CHK-003"></a>IKW-CHK-003	CHK	400	Non	Checkout session expirée
<a id="IKW-CHK-004"></a>IKW-CHK-004	CHK	400	Non	Checkout session non ouverte
<a id="IKW-CHK-005"></a>IKW-CHK-005	CHK	400	Non	Montant de checkout requis
<a id="IKW-CHK-006"></a>IKW-CHK-006	CHK	400	Non	Le checkout n’a pas de payment intent
<a id="IKW-CHK-007"></a>IKW-CHK-007	CHK	400	Non	Reçu indisponible
<a id="IKW-PAYOUT-001"></a>IKW-PAYOUT-001	PAYOUT	404	Non	Payout introuvable
<a id="IKW-PAYOUT-002"></a>IKW-PAYOUT-002	PAYOUT	400	Non	Destination invalide
<a id="IKW-PAYOUT-003"></a>IKW-PAYOUT-003	PAYOUT	402	Non	Balance de payout insuffisante
<a id="IKW-PAYOUT-004"></a>IKW-PAYOUT-004	PAYOUT	409	Non	Batch déjà en cours de traitement
<a id="IKW-PAYOUT-005"></a>IKW-PAYOUT-005	PAYOUT	409	Non	Batch déjà terminé
<a id="IKW-PAYOUT-006"></a>IKW-PAYOUT-006	PAYOUT	400	Non	Destinataire invalide
<a id="IKW-PAYOUT-007"></a>IKW-PAYOUT-007	PAYOUT	403	Non	Rejet AML
<a id="IKW-PAYOUT-008"></a>IKW-PAYOUT-008	PAYOUT	403	Non	Mismatch marchand
<a id="IKW-PAYOUT-009"></a>IKW-PAYOUT-009	PAYOUT	400	Non	Incohérence de devise
<a id="IKW-PAYOUT-010"></a>IKW-PAYOUT-010	PAYOUT	400	Non	Payout Invalid Amount
<a id="IKW-TRANSFER-001"></a>IKW-TRANSFER-001	TRANSFER	400	Non	Montant invalide
<a id="IKW-TRANSFER-002"></a>IKW-TRANSFER-002	TRANSFER	400	Non	Incohérence de devise
<a id="IKW-TRANSFER-003"></a>IKW-TRANSFER-003	TRANSFER	404	Non	Transfert ou paiement introuvable
<a id="IKW-TRANSFER-004"></a>IKW-TRANSFER-004	TRANSFER	409	Non	Transition d’état invalide
<a id="IKW-TRANSFER-005"></a>IKW-TRANSFER-005	TRANSFER	400	Non	Le remboursement dépasse le montant
<a id="IKW-TRANSFER-006"></a>IKW-TRANSFER-006	TRANSFER	409	Non	Déjà remboursé
<a id="IKW-TRANSFER-007"></a>IKW-TRANSFER-007	TRANSFER	502	Oui	Échec du provider
<a id="IKW-TRANSFER-008"></a>IKW-TRANSFER-008	TRANSFER	402	Non	Balance insuffisante
<a id="IKW-TRANSFER-009"></a>IKW-TRANSFER-009	TRANSFER	400	Non	Transfer Same Source Destination

Facturation, ledger, produits et configuration

Code	Module	HTTP	Retryable	Signification
<a id="IKW-BILLING-001"></a>IKW-BILLING-001	BILLING	404	Non	Facture introuvable
<a id="IKW-BILLING-002"></a>IKW-BILLING-002	BILLING	404	Non	Plan introuvable
<a id="IKW-BILLING-003"></a>IKW-BILLING-003	BILLING	500	Oui	Erreur de cycle de facturation
<a id="IKW-BILLING-004"></a>IKW-BILLING-004	BILLING	400	Non	Billing No Payment Attempt
<a id="IKW-CONFIG-001"></a>IKW-CONFIG-001	CONFIG	403	Non	Fonctionnalité désactivée
<a id="IKW-CONFIG-002"></a>IKW-CONFIG-002	CONFIG	400	Non	Pays/devise désactivé
<a id="IKW-LEDGER-001"></a>IKW-LEDGER-001	LEDGER	404	Non	Compte ledger introuvable
<a id="IKW-LEDGER-002"></a>IKW-LEDGER-002	LEDGER	402	Non	Balance insuffisante
<a id="IKW-LEDGER-003"></a>IKW-LEDGER-003	LEDGER	400	Non	Incohérence de devise
<a id="IKW-PRODUCT-001"></a>IKW-PRODUCT-001	PRODUCT	404	Non	Produit introuvable
<a id="IKW-PRODUCT-002"></a>IKW-PRODUCT-002	PRODUCT	400	Non	Nom de produit invalide
<a id="IKW-PRODUCT-003"></a>IKW-PRODUCT-003	PRODUCT	400	Non	Prix produit invalide

Sécurité, compliance, risque, webhook et providers externes

Code	Module	HTTP	Retryable	Signification
<a id="IKW-COMPLIANCE-001"></a>IKW-COMPLIANCE-001	COMPLIANCE	403	Non	KYC requis
<a id="IKW-COMPLIANCE-002"></a>IKW-COMPLIANCE-002	COMPLIANCE	400	Non	Document de conformité expiré
<a id="IKW-COMPLIANCE-003"></a>IKW-COMPLIANCE-003	COMPLIANCE	403	Non	Limite de conformité dépassée
<a id="IKW-EXTERNAL-001"></a>IKW-EXTERNAL-001	EXTERNAL	502	Oui	Provider indisponible
<a id="IKW-EXTERNAL-002"></a>IKW-EXTERNAL-002	EXTERNAL	504	Oui	Timeout du provider
<a id="IKW-EXTERNAL-003"></a>IKW-EXTERNAL-003	EXTERNAL	400	Non	Requête rejetée par le provider
<a id="IKW-RISK-001"></a>IKW-RISK-001	RISK	409	Non	Décision déjà prise sur le dossier de risque
<a id="IKW-RISK-002"></a>IKW-RISK-002	RISK	404	Non	Règle de risque introuvable
<a id="IKW-RISK-003"></a>IKW-RISK-003	RISK	409	Non	Impossible d’assigner le dossier de risque
<a id="IKW-SECURITY-001"></a>IKW-SECURITY-001	SECURITY	403	Non	MFA requis
<a id="IKW-SECURITY-002"></a>IKW-SECURITY-002	SECURITY	400	Non	Code MFA invalide
<a id="IKW-SECURITY-003"></a>IKW-SECURITY-003	SECURITY	429	Non	Trop de tentatives MFA
<a id="IKW-SECURITY-004"></a>IKW-SECURITY-004	SECURITY	400	Non	Passkey invalide
<a id="IKW-SECURITY-005"></a>IKW-SECURITY-005	SECURITY	400	Non	Échec Google OAuth
<a id="IKW-SECURITY-006"></a>IKW-SECURITY-006	SECURITY	409	Non	Google déjà lié
<a id="IKW-SECURITY-007"></a>IKW-SECURITY-007	SECURITY	429	Non	Cooldown de sécurité actif
<a id="IKW-SECURITY-008"></a>IKW-SECURITY-008	SECURITY	500	Non	Google non configuré
<a id="IKW-SECURITY-009"></a>IKW-SECURITY-009	SECURITY	400	Non	Email Google non vérifié
<a id="IKW-SECURITY-010"></a>IKW-SECURITY-010	SECURITY	400	Non	Challenge expiré
<a id="IKW-SECURITY-011"></a>IKW-SECURITY-011	SECURITY	400	Non	Challenge non vérifié
<a id="IKW-SECURITY-012"></a>IKW-SECURITY-012	SECURITY	400	Non	Mismatch de challenge
<a id="IKW-TERMINAL-001"></a>IKW-TERMINAL-001	TERMINAL	400	Non	Terminal Invalid Session
<a id="IKW-TERMINAL-002"></a>IKW-TERMINAL-002	TERMINAL	400	Non	Terminal Invalid Reader
<a id="IKW-TERMINAL-003"></a>IKW-TERMINAL-003	TERMINAL	409	Non	Terminal Invalid Transition
<a id="IKW-WEBHOOK-001"></a>IKW-WEBHOOK-001	WEBHOOK	404	Non	Endpoint webhook introuvable
<a id="IKW-WEBHOOK-002"></a>IKW-WEBHOOK-002	WEBHOOK	502	Oui	Échec de livraison webhook

Escrow, funding, marketplace, apps, environnement et connect

Code	Module	HTTP	Retryable	Signification
<a id="IKW-APP-001"></a>IKW-APP-001	APP	404	Non	App introuvable
<a id="IKW-APP-002"></a>IKW-APP-002	APP	403	Non	Kill switch d’app activé
<a id="IKW-APP-003"></a>IKW-APP-003	APP	403	Non	Installation inactive
<a id="IKW-CONNECT-001"></a>IKW-CONNECT-001	CONNECT	404	Non	Compte connecté introuvable
<a id="IKW-CONNECT-002"></a>IKW-CONNECT-002	CONNECT	400	Non	Configuration de compte connecté invalide
<a id="IKW-ENV-001"></a>IKW-ENV-001	ENV	412	Non	Test mode non activé
<a id="IKW-ENV-002"></a>IKW-ENV-002	ENV	423	Non	Test mode déjà actif
<a id="IKW-ENV-003"></a>IKW-ENV-003	ENV	403	Non	Env Context Missing
<a id="IKW-ENV-004"></a>IKW-ENV-004	ENV	403	Non	Env Context Mismatch
<a id="IKW-ENV-005"></a>IKW-ENV-005	ENV	400	Non	Env Context Invalid
<a id="IKW-ENV-006"></a>IKW-ENV-006	ENV	403	Non	Env Context Not Allowed
<a id="IKW-ESCROW-001"></a>IKW-ESCROW-001	ESCROW	404	Non	Contrat d’escrow introuvable
<a id="IKW-ESCROW-002"></a>IKW-ESCROW-002	ESCROW	409	Non	Transition d’escrow invalide
<a id="IKW-ESCROW-003"></a>IKW-ESCROW-003	ESCROW	409	Non	Un litige actif bloque l’opération
<a id="IKW-ESCROW-004"></a>IKW-ESCROW-004	ESCROW	400	Non	Incohérence de devise escrow
<a id="IKW-ESCROW-005"></a>IKW-ESCROW-005	ESCROW	403	Non	Mismatch marchand escrow
<a id="IKW-ESCROW-006"></a>IKW-ESCROW-006	ESCROW	403	Non	Fonctionnalité escrow désactivée
<a id="IKW-ESCROW-007"></a>IKW-ESCROW-007	ESCROW	409	Non	Opération escrow en doublon
<a id="IKW-FUNDING-001"></a>IKW-FUNDING-001	FUNDING	404	Non	Campagne de financement introuvable
<a id="IKW-FUNDING-002"></a>IKW-FUNDING-002	FUNDING	409	Non	Transition funding invalide
<a id="IKW-FUNDING-003"></a>IKW-FUNDING-003	FUNDING	400	Non	Montant insuffisant
<a id="IKW-FUNDING-004"></a>IKW-FUNDING-004	FUNDING	400	Non	Incohérence de devise funding
<a id="IKW-FUNDING-005"></a>IKW-FUNDING-005	FUNDING	403	Non	Mismatch marchand funding
<a id="IKW-FUNDING-006"></a>IKW-FUNDING-006	FUNDING	403	Non	Fonctionnalité funding désactivée
<a id="IKW-FUNDING-007"></a>IKW-FUNDING-007	FUNDING	409	Non	Contribution en doublon
<a id="IKW-FUNDING-008"></a>IKW-FUNDING-008	FUNDING	400	Non	Funding Target Amount Invalid
<a id="IKW-FUNDING-009"></a>IKW-FUNDING-009	FUNDING	400	Non	Funding Deadline Invalid
<a id="IKW-FUNDING-010"></a>IKW-FUNDING-010	FUNDING	409	Non	Funding Deadline Not Reached
<a id="IKW-MKTPLACE-001"></a>IKW-MKTPLACE-001	MKTPLACE	403	Non	Vendeur suspendu
<a id="IKW-MKTPLACE-002"></a>IKW-MKTPLACE-002	MKTPLACE	400	Non	Commande marketplace invalide
<a id="IKW-MKTPLACE-003"></a>IKW-MKTPLACE-003	MKTPLACE	400	Non	Erreur de commission
<a id="IKW-MKTPLACE-004"></a>IKW-MKTPLACE-004	MKTPLACE	400	Non	Incohérence de devise marketplace
<a id="IKW-MKTPLACE-005"></a>IKW-MKTPLACE-005	MKTPLACE	403	Non	Mismatch marchand marketplace
<a id="IKW-MKTPLACE-006"></a>IKW-MKTPLACE-006	MKTPLACE	400	Non	Remboursement marketplace non autorisé
<a id="IKW-MKTPLACE-007"></a>IKW-MKTPLACE-007	MKTPLACE	409	Non	Marketplace Invalid Transition
<a id="IKW-MKTPLACE-008"></a>IKW-MKTPLACE-008	MKTPLACE	400	Non	Marketplace Seller Invalid
<a id="IKW-MKTPLACE-009"></a>IKW-MKTPLACE-009	MKTPLACE	400	Non	Marketplace Refund Amount Invalid

Paiements groupés (Disbursement) et instructions

Code	Module	HTTP	Retryable	Signification
<a id="IKW-DISB-001"></a>IKW-DISB-001	DISB	404	Non	Disbursement Batch Not Found
<a id="IKW-DISB-002"></a>IKW-DISB-002	DISB	409	Non	Disbursement Batch Already Processing
<a id="IKW-DISB-003"></a>IKW-DISB-003	DISB	409	Non	Disbursement Batch Already Completed
<a id="IKW-DISB-004"></a>IKW-DISB-004	DISB	409	Non	Disbursement Batch Already Canceled
<a id="IKW-DISB-005"></a>IKW-DISB-005	DISB	409	Non	Disbursement Batch Not Cancelable
<a id="IKW-DISB-006"></a>IKW-DISB-006	DISB	400	Non	Disbursement Batch Validation Failed
<a id="IKW-DISB-007"></a>IKW-DISB-007	DISB	404	Non	Disbursement Instruction Not Found
<a id="IKW-DISB-008"></a>IKW-DISB-008	DISB	400	Non	Disbursement Instruction Invalid Amount
<a id="IKW-DISB-009"></a>IKW-DISB-009	DISB	400	Non	Disbursement Instruction Missing Dest
<a id="IKW-DISB-010"></a>IKW-DISB-010	DISB	404	Non	Disbursement Recipient Not Found
<a id="IKW-DISB-011"></a>IKW-DISB-011	DISB	409	Non	Disbursement Recipient Archived
<a id="IKW-DISB-012"></a>IKW-DISB-012	DISB	402	Non	Disbursement Insufficient Balance
<a id="IKW-DISB-013"></a>IKW-DISB-013	DISB	400	Non	Disbursement Currency Invalid
<a id="IKW-DISB-014"></a>IKW-DISB-014	DISB	403	Non	Disbursement Approval Required
<a id="IKW-DISB-015"></a>IKW-DISB-015	DISB	403	Non	Disbursement Approval Self Approval
<a id="IKW-DISB-016"></a>IKW-DISB-016	DISB	409	Non	Disbursement Approval Already Decided
<a id="IKW-DISB-017"></a>IKW-DISB-017	DISB	403	Non	Disbursement Merchant Mismatch
<a id="IKW-DISB-018"></a>IKW-DISB-018	DISB	403	Non	Disbursement Environment Mismatch
<a id="IKW-DISB-019"></a>IKW-DISB-019	DISB	400	Non	Disbursement Schedule Invalid
<a id="IKW-DISB-020"></a>IKW-DISB-020	DISB	409	Non	Disbursement Export No Failed Items
<a id="IKW-DISB-021"></a>IKW-DISB-021	DISB	409	Non	Disbursement Batch Not Resumable

Alias moteurs rétrocompatibles

Le catalogue mappe également les chaînes d’erreur des anciens moteurs vers les codes plateforme canoniques.

Exemples :

• PayoutEngine:BatchNotFound → IKW-PAYOUT-001
• EscrowEngine:ContractNotFound → IKW-ESCROW-001
• FundingEngine:CampaignNotFound → IKW-FUNDING-001
• MarketplaceEngine:SellerSuspended → IKW-MKTPLACE-001

Comment gérer les erreurs

• Utilisez code comme clé programmatique pour la logique conditionnelle.
• Utilisez le HTTP status pour le comportement au niveau transport.
• Ne faites un retry que lorsque le catalogue marque effectivement la condition comme retryable, par exemple pour les limites de débit, l’indisponibilité provider ou les timeouts.
• Pour les flux à portée marchande, privilégiez des indications d’action utilisateur plutôt que des termes internes bruts d’implémentation.

Sections liées

• Référence API
• Environnement Sandbox
• Vue d’ensemble Webhooks
• Onboarding marchand