Codes d'erreur

L’enveloppe

Toute erreur a la même forme, plate. Aucune imbrication, aucun details.

{ "error": "Insufficient balance. Available: 10.000000, Requested: 50.000000", "code": "INSUFFICIENT_BALANCE" }

Branchez-vous sur code, jamais sur error. La chaîne error est un texte destiné à vos journaux et à vos écrans de support ; elle peut être reformulée à tout moment et ne fait pas partie du contrat. code, si.

La plupart des échecs portent un code générique, pas un code nommé

C’est la partie qu’un catalogue dissimule d’ordinaire, elle passe donc en premier.

L’API lève 326 erreurs sans code métier, contre 46 codes publics nommés. Ces 326 retombent sur l’un des codes génériques ci-dessous, déduit du seul statut HTTP. En pratique, vous rencontrerez VALIDATION_ERROR et NOT_FOUND bien plus souvent que n’importe quel code spécifique.

Donc : construisez votre gestion d’erreurs autour des codes génériques, et traitez les codes nommés comme des précisions. Une intégration qui ne gère que les codes nommés sera surprise par le cas courant.

Code	HTTP	Signification	Que faire
VALIDATION_ERROR	400	La requête a échoué à la validation, sans raison plus précise. Lisez error.	Corrigez la requête. Non réessayable en l’état.
UNAUTHORIZED	401	L’authentification a échoué, sans raison plus précise.	Vérifiez vos identifiants et votre signature. Non réessayable en l’état.
FORBIDDEN	403	Authentifié, mais l’action n’est pas permise.	Vérifiez les scopes de la clé et l’état du workspace. Action humaine.
NOT_FOUND	404	La ressource n’existe pas, ou ne vous appartient pas.	Vérifiez l’identifiant. Terminal pour cet identifiant.
CONFLICT	409	La requête entre en conflit avec l’état courant.	Relisez la ressource, puis décidez.
UNPROCESSABLE	422	Bien formée, mais rejetée par une règle métier sans code dédié. Lisez error.	Corrigez l’entrée ou l’état. Non réessayable en l’état.
INTERNAL_ERROR	500	Erreur serveur inattendue. Le détail est journalisé chez nous, jamais renvoyé.	Réessayable. Réessayez avec un délai croissant ; si cela persiste, contactez [email protected] avec l’horodatage.
DATABASE_ERROR	500	Erreur de base de données. Le détail sous-jacent n’est jamais renvoyé.	Réessayable. Comme ci-dessus.

Authentification et signature

Code	HTTP	Cause	Que faire
MISSING_AUTH_HEADERS	401	L’un des trois en-têtes X-CowriePay-* est absent.	Envoyez les trois. Voir le guide Authentification.
INVALID_SIGNATURE	401	Le HMAC ne correspond pas à la chaîne de signature.	Journalisez la chaîne exacte ; vérifiez que vous avez haché le corps brut et inclus /v2 ainsi que la chaîne de requête.
TIMESTAMP_EXPIRED	401	L’horodatage sort de la tolérance de décalage d’horloge.	Synchronisez votre horloge (NTP), puis réessayez. Réessayable une fois corrigé.
REPLAY_DETECTED	401	La même signature a été présentée deux fois dans la fenêtre de rejeu.	Utilisez un horodatage neuf à chaque requête. Ne renvoyez jamais une requête signée telle quelle.
INVALID_API_KEY	401	Clé inconnue ou révoquée.	Vérifiez l’identifiant de la clé. Action humaine.
API_KEY_EXPIRED	401	La clé a dépassé sa date d’expiration.	Créez une nouvelle clé. Action humaine.
IP_NOT_ALLOWED	403	L’IP appelante n’est pas sur la liste d’autorisation de la clé.	Ajoutez l’IP, ou appelez depuis une IP autorisée. Action humaine.
INSUFFICIENT_SCOPE	403	La clé n’a pas le scope exigé par cet endpoint.	Créez une clé portant ce scope. Action humaine.
WORKSPACE_INACTIVE	401	Le workspace est suspendu ou fermé.	Contactez le support. Terminal jusqu’à résolution.

Forme de la requête, idempotence et limites de débit

Code	HTTP	Cause	Que faire
INVALID_JSON	400	Le corps n’est pas du JSON valide.	Corrigez la sérialisation.
PAYLOAD_TOO_LARGE	413	Le corps dépasse 50 ko.	Envoyez moins.
UNSUPPORTED_MEDIA_TYPE	415	Le jeu de caractères ou l’encodage du corps n’est pas pris en charge.	Envoyez du JSON en UTF-8.
IDEMPOTENCY_KEY_INVALID	400	L’en-tête Idempotency-Key n’est pas composé de 1 à 255 caractères A-Z a-z 0-9 _ -.	Corrigez le format de la clé.
IDEMPOTENCY_CONFLICT	409	Une requête portant cette clé est encore en cours.	Réessayable. Patientez et réessayez avec LA MÊME clé.
IDEMPOTENCY_MISMATCH	422	La même clé a été réutilisée avec un corps différent.	Utilisez une clé neuve, ou renvoyez le corps d’origine. Non réessayable en l’état.
RATE_LIMITED	429	Trop de requêtes.	Réessayable. Espacez et réessayez.

Blockchains et disponibilité

Code	HTTP	Cause	Que faire
CHAIN_NOT_ENABLED	422	La blockchain n’est pas ouverte aux nouvelles opérations. Elles sont fermées par défaut.	Appelez List the chains open for new operations et ne proposez que celles-là.
FEATURE_NOT_AVAILABLE	422	La fonctionnalité n’est pas activée pour votre workspace.	Contactez le support si vous attendiez cet accès. Action humaine.

Retraits et sécurité

Code	HTTP	Cause	Que faire
INSUFFICIENT_BALANCE	422	Le solde disponible est inférieur au montant demandé.	Approvisionnez le workspace, ou demandez moins.
INVALID_DESTINATION_ADDRESS	400	L’adresse n’est pas valide pour cette blockchain.	Validez avant de soumettre.
DESTINATION_IS_INTERNAL	422	La destination est une adresse gérée par CowriePay. Les transferts on-chain entre adresses CowriePay ne sont pas autorisés.	Retirez vers une adresse externe.
WITHDRAWALS_FROZEN	422	Les retraits sont gelés pour ce workspace.	Contactez le support. Terminal jusqu’à résolution.
WITHDRAWAL_NOT_CANCELLABLE	422	Le retrait a dépassé l’état annulable.	Rien à faire : il est déjà en traitement ou réglé. Terminal.
WORKSPACE_NOT_FOUND	422	Le workspace n’existe pas.	Vérifiez votre clé.
SYSTEM_WORKSPACE_PROTECTED	422	La cible est un workspace interne protégé.	Vous ne devriez pas voir ceci ; contactez le support si cela arrive.

Faucet de la Sandbox

Ces codes n’apparaissent qu’en Sandbox, sur l’endpoint du faucet. C’est le plus grand groupe nommé, parce que le faucet valide beaucoup de choses avant de distribuer.

Code	HTTP	Cause	Que faire
FAUCET_ONLY_SANDBOX	403	Appelé avec une clé de production.	Utilisez une clé cpk_test_.
FAUCET_NOT_SANDBOX	422	Le wallet visé n’est pas un wallet de sandbox.	Utilisez un wallet de testnet.
FAUCET_ADDRESS_NOT_FOUND	422	L’adresse n’est pas l’un de vos wallets.	Créez d’abord le wallet.
FAUCET_INVALID_ASSET	400	L’actif n’est pas distribuable sur cette blockchain.	Vérifiez le couple actif et blockchain.
FAUCET_INVALID_AMOUNT	400	Le montant n’est pas un nombre valide, ou sort des bornes.	Corrigez le montant.
FAUCET_AMOUNT_OVER_CAP	422	Au-dessus du plafond par distribution.	Demandez moins, ou distribuez deux fois.
FAUCET_NO_ASSETS	400	Aucun actif demandé.	Envoyez-en au moins un.
FAUCET_DUPLICATE_ASSET	422	Le même actif figure deux fois dans une requête.	Dédupliquez.
FAUCET_TOO_MANY_ITEMS	422	Trop d’actifs dans une seule requête.	Découpez la requête.
FAUCET_RATE_LIMITED	422	Trop de distributions dans la fenêtre.	Réessayable. Patientez et réessayez.
FAUCET_NATIVE_REQUIRES_DEPOSIT	422	Une distribution native exige un dépôt de jeton existant sur ce wallet.	Distribuez d’abord le jeton.
FAUCET_NATIVE_BUDGET_EXCEEDED	422	Le budget natif du workspace pour la fenêtre est épuisé.	Réessayable plus tard. Attendez le renouvellement de la fenêtre.
FAUCET_DISPENSER_EXHAUSTED	422	Le wallet distributeur partagé est vide.	Ce n’est pas de votre fait. Contactez le support ; nous réapprovisionnons.

Une note sur les avertissements

Certaines réponses 200 portent un tableau warnings[] avec ses propres codes, par exemple lorsqu’un dépôt est sous le minimum de consolidation. Ce ne sont pas des erreurs : la requête a réussi. Ils sont documentés avec les endpoints qui les émettent, pas ici, pour que cette page reste une liste de ce qui a échoué.