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 lisible par un humain",
    "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
IKW-AUTH-001	AUTH	401	Non	Identifiants invalides
IKW-AUTH-002	AUTH	401	Non	Authentification requise
IKW-AUTH-003	AUTH	401	Non	Token révoqué
IKW-AUTH-004	AUTH	401	Non	Token expiré
IKW-AUTH-005	AUTH	401	Non	Token invalide
IKW-AUTH-006	AUTH	401	Non	Session expirée
IKW-AUTH-007	AUTH	401	Non	Session révoquée
IKW-AUTH-008	AUTH	401	Non	Clé API expirée
IKW-AUTH-009	AUTH	401	Non	Clé API tournée
IKW-AUTHZ-001	AUTHZ	403	Non	Interdit
IKW-AUTHZ-002	AUTHZ	403	Non	Rôle insuffisant
IKW-AUTHZ-003	AUTHZ	403	Non	Membership requis

Fondations marchand, requête et système

Code	Module	HTTP	Retryable	Signification
IKW-MERCHANT-001	MERCHANT	404	Non	Marchand introuvable
IKW-MERCHANT-002	MERCHANT	403	Non	Marchand désactivé
IKW-MERCHANT-003	MERCHANT	409	Non	Le marchand existe déjà
IKW-MERCHANT-004	MERCHANT	410	Non	Invitation marchand expirée
IKW-MERCHANT-005	MERCHANT	404	Non	Compte marchand introuvable
IKW-REQ-001	REQ	400	Non	Entrée invalide
IKW-REQ-002	REQ	400	Non	Paramètre requis manquant
IKW-REQ-003	REQ	400	Non	Paramètre invalide
IKW-REQ-004	REQ	409	Non	Conflit d’idempotence
idempotency_key_conflict	REQ	409	Non	Alias rétrocompatible de conflit d’idempotence
IKW-RES-001	RES	404	Non	Ressource introuvable
IKW-RES-002	RES	409	Non	La ressource existe déjà
IKW-RES-003	RES	409	Non	Conflit d’état de ressource
IKW-RATE-001	RATE	429	Oui	Trop de requêtes
IKW-SYS-001	SYS	500	Non	Erreur interne
IKW-SYS-002	SYS	503	Oui	Service indisponible
IKW-SYS-003	SYS	504	Oui	Timeout système

Checkout, paiements, remboursements et payouts

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

Facturation, ledger, produits et configuration

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

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

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

Escrow, funding, marketplace, apps, environnement et connect

Code	Module	HTTP	Retryable	Signification
IKW-ESCROW-001	ESCROW	404	Non	Contrat d’escrow introuvable
IKW-ESCROW-002	ESCROW	409	Non	Transition d’escrow invalide
IKW-ESCROW-003	ESCROW	409	Non	Un litige actif bloque l’opération
IKW-ESCROW-004	ESCROW	400	Non	Incohérence de devise escrow
IKW-ESCROW-005	ESCROW	403	Non	Mismatch marchand escrow
IKW-ESCROW-006	ESCROW	403	Non	Fonctionnalité escrow désactivée
IKW-ESCROW-007	ESCROW	409	Non	Opération escrow en doublon
IKW-FUNDING-001	FUNDING	404	Non	Campagne de financement introuvable
IKW-FUNDING-002	FUNDING	409	Non	Transition funding invalide
IKW-FUNDING-003	FUNDING	400	Non	Montant insuffisant
IKW-FUNDING-004	FUNDING	400	Non	Incohérence de devise funding
IKW-FUNDING-005	FUNDING	403	Non	Mismatch marchand funding
IKW-FUNDING-006	FUNDING	403	Non	Fonctionnalité funding désactivée
IKW-FUNDING-007	FUNDING	409	Non	Contribution en doublon
IKW-MKTPLACE-001	MKTPLACE	403	Non	Vendeur suspendu
IKW-MKTPLACE-002	MKTPLACE	400	Non	Commande marketplace invalide
IKW-MKTPLACE-003	MKTPLACE	400	Non	Erreur de commission
IKW-MKTPLACE-004	MKTPLACE	400	Non	Incohérence de devise marketplace
IKW-MKTPLACE-005	MKTPLACE	403	Non	Mismatch marchand marketplace
IKW-MKTPLACE-006	MKTPLACE	400	Non	Remboursement marketplace non autorisé
IKW-APP-001	APP	404	Non	App introuvable
IKW-APP-002	APP	403	Non	Kill switch d’app activé
IKW-APP-003	APP	403	Non	Installation inactive
IKW-ENV-001	ENV	412	Non	Test mode non activé
IKW-ENV-002	ENV	423	Non	Test mode déjà actif
IKW-CONNECT-001	CONNECT	404	Non	Compte connecté introuvable
IKW-CONNECT-002	CONNECT	400	Non	Configuration de compte connecté invalide

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