Codes d'erreur et statuts HTTP

Chaque échec renvoie un code stable, lisible par une machine, à côté du statut HTTP. Branchez-vous sur le code, jamais sur le texte du message : les messages sont écrits pour des humains et peuvent être reformulés, tandis que les codes font partie du contrat.

L'ensemble des 42 codes que l'API revendeur peut renvoyer, regroupés par nature du problème. Chaque entrée précise le statut HTTP qui l'accompagne et le changement qui la résout.

Authentification (401)

Code	HTTP	Signification	Comment le corriger
MISSING_API_KEY	401	Clé API requiseAucun en-tête Authorization n'a été envoyé, ou son format est incorrect.	Ajoutez l'en-tête : Authorization: Bearer <keyId>.<secret>action: FIX_INPUT · retryable: false · retry_after: null
INVALID_API_KEY	401	Clé API invalideLa clé API fournie ne correspond à aucune clé active.	Vérifiez votre ID de clé et votre secret. Au besoin, régénérez la clé depuis le panneau Accès API.action: FIX_INPUT · retryable: false · retry_after: null

Autorisation (403)

Code	HTTP	Signification	Comment le corriger
ACCOUNT_DISABLED	403	Compte désactivéCe code n'est plus renvoyé. Un compte qui ne peut pas passer de commande reçoit ACCOUNT_FROZEN (HTTP 403).	Gérez ACCOUNT_FROZEN à la place.Plus renvoyé, remplacé par ACCOUNT_FROZEN
ACCOUNT_FROZEN	403	Compte geléVotre compte a été gelé temporairement, en général à cause d'une activité suspecte.	Contactez le support pour faire dégeler votre compte.action: CONTACT_SUPPORT · retryable: false · retry_after: null
IP_NOT_ALLOWED	403	Adresse IP absente de la liste autoriséeLa requête provient d'une adresse IP qui ne figure pas dans la liste autorisée de votre clé API.	Ajoutez l'IP de votre serveur à la liste autorisée dans le panneau Accès API, ou supprimez les restrictions d'IP.action: FIX_INPUT · retryable: false · retry_after: null

Validation de la requête (400)

Code	HTTP	Signification	Comment le corriger
MISSING_REQUIRED_FIELD	400	Champ obligatoire manquantUn champ obligatoire manque dans le corps de la requête. Pour les champs liés au joueur, details.field indique le champ manquant.	Consultez la documentation de l'endpoint, ainsi que GET /catalog/category/:categoryId/requirements pour les champs joueur, puis envoyez tous les champs obligatoires.action: FIX_INPUT · retryable: false · retry_after: null
INVALID_PARAMETER_FORMAT	400	Format de paramètre invalideUn champ requis n'a pas le bon format (du texte dans un champ numérique, par exemple). La propriété details.field indique de quel champ il s'agit.	Relisez les champs requis de la catégorie et envoyez ce champ au format attendu par son data_type et ses règles de validation.action: FIX_INPUT · retryable: false · retry_after: null
INVALID_PARAMETER_VALUE	400	Valeur de paramètre invalideLa valeur d'un champ requis sort des valeurs autorisées : sous le minimum, au-dessus du maximum ou absente de ses select_options. Le champ en cause figure dans details.field.	Envoyez une valeur que les champs requis de la catégorie acceptent pour ce champ.action: FIX_INPUT · retryable: false · retry_after: null
INVALID_PARAMETER_LENGTH	400	Longueur de paramètre invalideUn champ requis est trop court ou trop long par rapport à la limite autorisée. Vous retrouvez dans details.field le nom du champ en question.	Vérifiez min_length / max_length dans les champs requis de la catégorie.action: FIX_INPUT · retryable: false · retry_after: null
INVALID_UUID_FORMAT	400	Format UUID invalideL'order_id n'est pas un UUID valide.	Utilisez n'importe quel format UUID valide (v1, v4, v7, etc.). Format : xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.action: FIX_INPUT · retryable: false · retry_after: null
INVALID_QUANTITY	400	Quantité invalideLa quantité doit être un entier positif.	Indiquez une quantité entière >= 1.action: FIX_INPUT · retryable: false · retry_after: null
INVALID_CATEGORY_ID	400	ID de catégorie invalideLe categoryId fourni n'est pas un nombre valide.	Retrouvez les ID de catégorie valides avec l'explorateur de catalogue ou GET /catalog/categories.action: FIX_INPUT · retryable: false · retry_after: null
INVALID_BIG_CATEGORY_ID	400	ID de catégorie principale invalideLe bigCategoryId fourni n'est pas un nombre valide.	L'explorateur de catalogue ou GET /catalog/big-categories vous donne les ID de catégorie principale valides.action: FIX_INPUT · retryable: false · retry_after: null
INVALID_ITEM_ID	400	ID d'article invalideL'ID d'article fourni n'est pas valide.	Consultez l'explorateur de catalogue ou GET /catalog/subcategories pour trouver des ID d'article valides.action: FIX_INPUT · retryable: false · retry_after: null
INVALID_SUBCATEGORY	400	Sous-catégorie invalideCet ID de sous-catégorie n'existe pas.	Vérifiez le sub_category_id via les endpoints du catalogue.action: FIX_INPUT · retryable: false · retry_after: null
INVALID_PRODUCT_CONFIG	400	Configuration produit invalideCe code n'est plus renvoyé. Un champ requis manquant renvoie désormais MISSING_REQUIRED_FIELD, et un produit qui ne peut pas être vendu pour le moment renvoie PRODUCT_UNAVAILABLE.	Gérez plutôt MISSING_REQUIRED_FIELD et PRODUCT_UNAVAILABLE.Plus renvoyé, remplacé par MISSING_REQUIRED_FIELD
INVALID_PAGINATION	400	Paramètres de pagination invalidesLes valeurs de page ou de limit sortent de la plage autorisée.	Utilisez page >= 1 et un limit compris entre 1 et 100.action: FIX_INPUT · retryable: false · retry_after: null
INVALID_DATE_FORMAT	400	Format de date invalideLe paramètre created_after ou created_before n'est pas une date ISO 8601 valide.	Respectez le format ISO 8601 : 2024-01-01T00:00:00Z.action: FIX_INPUT · retryable: false · retry_after: null

Vérification du joueur (400 / 429 / 503)

Code	HTTP	Signification	Comment le corriger
PLAYER_NOT_FOUND	400	Joueur introuvableLe jeu a confirmé que cet ID joueur n'existe pas. Ce code n'apparaît que sur une réponse confirmée. Si l'ID ne peut pas être vérifié, vous recevez PLAYER_CHECK_UNAVAILABLE.	Vérifiez l'ID joueur. Regardez aussi si le jeu exige un zone_id.action: FIX_INPUT · retryable: false · retry_after: null
PLAYER_CHECK_UNAVAILABLE	503	Impossible de vérifier les ID joueur de ce jeu pour le momentLes ID joueur de ce jeu ne peuvent pas être vérifiés en ce moment. L'ID joueur n'a PAS été refusé.	Renvoyez la même requête après retry_after secondes. N'annoncez pas à votre client que son ID est faux.action: RETRY_LATER · retryable: true · retry_after: 60
PLAYER_BUSY	429	Cet ID joueur est déjà en cours de vérificationUne autre requête pour le même ID joueur est encore en cours de vérification.	Réessayez après retry_after secondes.action: RETRY_SOON · retryable: true · retry_after: 5
PLAYER_VALIDATION_FAILED	400	Échec de la validation du joueurCe code n'est plus renvoyé. Un ID joueur impossible à vérifier pour le moment renvoie PLAYER_CHECK_UNAVAILABLE (HTTP 503).	Gérez plutôt PLAYER_CHECK_UNAVAILABLE.Plus renvoyé, remplacé par PLAYER_CHECK_UNAVAILABLE
REGION_MISMATCH	400	La région de ce joueur ne peut pas recevoir ce produitLe joueur appartient à une région où ce produit ne peut pas être livré. L'erreur contient player_region et player_name.	Choisissez le produit qui correspond à la région du joueur.action: CHOOSE_OTHER · retryable: false · retry_after: null

Règles métier (400 / 409)

Code	HTTP	Signification	Comment le corriger
INSUFFICIENT_BALANCE	400	Solde du portefeuille insuffisantVotre portefeuille ne contient pas assez de fonds pour finaliser cette commande.	Alimentez votre portefeuille depuis la page de recharge avant de commander.action: TOP_UP · retryable: false · retry_after: null
OUT_OF_STOCK	400	Produit en rupture de stockCe produit est en rupture de stock pour le moment.	Réessayez plus tard ou choisissez un autre produit.action: RETRY_LATER · retryable: true · retry_after: null
INSUFFICIENT_STOCK	400	Moins d'unités disponibles que demandéLe stock disponible est inférieur à la quantité commandée. Contrairement à OUT_OF_STOCK, vous pouvez agir ici : error.max_quantity indique combien d'unités peuvent être commandées en ce moment. Rien n'a été débité.	Renvoyez la commande avec une quantité égale ou inférieure à error.max_quantity.action: FIX_INPUT · retryable: false · retry_after: null
PRODUCT_UNAVAILABLE	409	Ce produit est temporairement indisponibleLe produit existe, mais il ne peut pas être vendu pour le moment.	Réessayez plus tard ou choisissez un autre produit.action: RETRY_LATER · retryable: true · retry_after: null
PRICING_UPDATING	409	Le prix du produit est en cours de mise à jourLe prix de ce produit est en train d'être actualisé.	Après retry_after secondes, renvoyez la même requête, puis vérifiez de nouveau le prix.action: RETRY_SOON · retryable: true · retry_after: 30
OFFER_NOT_FOUND	400	Cette offre n'est pas disponible pour ce compte joueurUne offre à usage unique (par exemple un bonus de première recharge) n'est pas disponible pour ce compte joueur. Elle a peut-être déjà été utilisée.	Choisissez un autre produit pour ce joueur.action: CHOOSE_OTHER · retryable: false · retry_after: null
DUPLICATE_ORDER	409	ID de commande en doubleUne commande avec cet UUID existe déjà. Il s'agit d'une protection d'idempotence.	Générez un nouvel UUID pour une nouvelle commande. Si vous recevez cette erreur lors d'une nouvelle tentative, la première a abouti : consultez cette commande avec GET /orders/{orderId} au lieu d'en créer une autre.action: CHECK_ORDER · retryable: false · retry_after: null
PRICE_INCREASED	400	Le prix a augmenté au-delà de la valeur attendueLe prix unitaire actuel est supérieur à la valeur expected_unit_price que vous avez fournie.	Récupérez le dernier prix avec GET /catalog/subcategory/:id/price, puis mettez à jour expected_unit_price.action: FIX_INPUT · retryable: false · retry_after: null
SUBCATEGORY_DISABLED	400	Sous-catégorie désactivéeCette erreur n'est plus renvoyée. Un produit qui ne peut pas être vendu pour le moment répond PRODUCT_UNAVAILABLE (HTTP 409).	Gérez plutôt PRODUCT_UNAVAILABLE.Plus renvoyé, remplacé par PRODUCT_UNAVAILABLE

Introuvable (404)

Code	HTTP	Signification	Comment le corriger
ORDER_NOT_FOUND	404	Commande introuvableAucune commande n'existe avec l'ID de commande indiqué.	Vérifiez que l'ID de commande est correct.action: FIX_INPUT · retryable: false · retry_after: null
ITEM_NOT_FOUND	404	Article introuvableL'article du catalogue demandé n'existe pas.	Utilisez les endpoints du catalogue pour trouver des ID d'article valides.action: FIX_INPUT · retryable: false · retry_after: null
NO_REQUIREMENTS_FOUND	404	Aucun prérequis trouvé pour cette catégorieCette catégorie n'a aucun prérequis joueur à renvoyer pour le moment.	Revenez plus tard ou sélectionnez une autre catégorie.action: RETRY_LATER · retryable: true · retry_after: null
ITEM_NOT_AVAILABLE	404	Article indisponibleCode retiré : il n'est plus renvoyé. Un article qui existe mais ne peut pas être vendu pour le moment répond PRODUCT_UNAVAILABLE (HTTP 409).	Gérez PRODUCT_UNAVAILABLE à la place.Plus renvoyé, remplacé par PRODUCT_UNAVAILABLE

Validation des requêtes groupées (400)

Code	HTTP	Signification	Comment le corriger
INVALID_ORDER_IDS_FORMAT	400	Format de order_ids invalideLe champ order_ids doit être un tableau de chaînes de caractères.	Envoyez order_ids sous cette forme : { "order_ids": ["uuid1", "uuid2"] }.action: FIX_INPUT · retryable: false · retry_after: null
EMPTY_ORDER_IDS	400	Tableau order_ids videLe tableau order_ids ne peut pas être vide.	Indiquez au moins un ID de commande dans le tableau.action: FIX_INPUT · retryable: false · retry_after: null
TOO_MANY_ORDER_IDS	400	Trop d'ID de commandeVous pouvez interroger 50 ID de commande au maximum en une seule fois.	Répartissez votre requête en lots de 50 ou moins.action: FIX_INPUT · retryable: false · retry_after: null

Limitation de débit (429)

Code	HTTP	Signification	Comment le corriger
RATE_LIMIT_EXCEEDED	429	Limite de requêtes dépasséeVous avez dépassé la limite de cet endpoint. Les quotas par minute (catalog, orders, account) renvoient X-RateLimit-Limit, X-RateLimit-Remaining et X-RateLimit-Reset à chaque réponse, et details reprend limit, remaining (0), retry_after et window_seconds. POST /player/validate est décompté sur votre quota quotidien de vérifications joueur : il n'envoie aucun en-tête X-RateLimit, et sa réponse 429 contient limit, current, remaining, reset_at et reset_in_seconds dans error. Dans les deux cas, error.retry_after et l'en-tête Retry-After indiquent le nombre de secondes à attendre.	Attendez le nombre de secondes indiqué dans retry_after ou dans l'en-tête Retry-After avant de réessayer. Sur les endpoints limités à la minute, surveillez X-RateLimit-Remaining pour éviter d'atteindre la limite.action: RETRY_LATER · retryable: true · retry_after: secondes avant la réinitialisation

Côté serveur (5xx)

Code	HTTP	Signification	Comment le corriger
INTERNAL_ERROR	500	Erreur interne du serveurUne erreur inattendue s'est produite sur le serveur.	Renvoyez la requête après retry_after secondes. Pour POST /orders/create, réutilisez le même order_id : la commande ne pourra ainsi jamais être créée deux fois. Si le problème persiste, contactez le support.action: RETRY_LATER · retryable: true · retry_after: 30
SERVICE_UNAVAILABLE	503	Service temporairement indisponibleCe code n'est plus renvoyé. Une panne côté serveur répond INTERNAL_ERROR (HTTP 500) ; le seul code 503 est PLAYER_CHECK_UNAVAILABLE, lorsqu'un ID joueur ne peut pas être vérifié pour le moment.	Traitez plutôt INTERNAL_ERROR et PLAYER_CHECK_UNAVAILABLE.Plus renvoyé, remplacé par INTERNAL_ERROR

Nouveau sur la plateforme ? Commencez par la présentation de l'API de recharge de jeux pour revendeurs, ou lisez la présentation du programme revendeur SHOP2TOPUP pour comprendre le fonctionnement du compte partenaire.