Gestion des erreurs - HUB2 Documentation

Format des erreurs

Les erreurs renvoyées par l’API HUB2 utilisent le format suivant (certains points de terminaison de conformité renvoient statusCode, message et error pour les réponses 404). Les requêtes rejetées par le pare-feu applicatif (WAF) renvoient à la place un 403 avec un corps HTML (voir Sécurité).

Nom du champ	Description
`status`	Le code de statut HTTP
`code`	Un code d’erreur métier défini par l’API HUB2 (voir la liste ci-dessous)
`message`	Une description lisible de l’erreur
`request_id`	Identifiant unique de la requête

Exemple : erreur 404

{
    "status": 404,
    "code": "Not Found",
    "message": "Country not found",
    "request_id": "req_RRg_xtA55q32PLIWYVLFL"
}

Indiquez la valeur de request_id lorsque vous contactez le support HUB2 ; elle permet à l’équipe de retrouver votre requête et de répondre plus rapidement.

Codes d’erreur

Codes de statut HTTP

Les codes de statut HTTP n’indiquent pas d’erreurs applicatives.

Codes de statut HTTP standards que l’API HUB2 peut renvoyer :

Code de statut	Texte de statut	Description
`200`	`OK`	La requête s’est exécutée comme prévu.
`201`	`Created`	La ressource a été créée.
`202`	`Accepted`	La requête a été acceptée pour un traitement asynchrone.
`400`	`Bad Request`	La requête est invalide, souvent en raison d’un paramètre manquant ou mal formaté.
`401`	`Unauthorized`	Aucune clé API valide n’a été fournie.
`403`	`Forbidden`	La clé API n’a pas les permissions nécessaires pour effectuer la requête.
`404`	`Not Found`	La ressource demandée n’existe pas.
`409`	`Conflict`	La requête est en conflit avec une autre action déjà en cours ou déjà terminée.
`422`	`Unprocessable Entity`	Les paramètres sont valides, mais la requête n’a pas pu être traitée.
`429`	`Too Many Requests`	Trop de requêtes ont été envoyées en peu de temps. La requête a été rejetée pour préserver les performances globales de l’API. Voir Limites de flux.
`500`, `501`, `502`, `503`, `504`	Erreurs serveur	Une erreur s’est produite du côté de HUB2.

Codes d’erreur applicatifs

Codes d’erreur applicatifs que l’API HUB2 peut renvoyer :

Code	Motif
`account-already-exists`	Un compte de ce type existe déjà pour le marchand dans ce mode (live ou sandbox).
`cancellation-already-done`	La transaction a déjà été annulée.
`insufficient-funds`	Le compte ne dispose pas de fonds suffisants pour transférer le montant demandé.
`invalid-currency`	La devise est invalide.
`locked-account`	Le compte est verrouillé.
`transaction-not-found`	La transaction est introuvable pour ce compte.
`currency-not-found`	La devise est introuvable.
`withdrawal-unavailable`	Les retraits sont indisponibles sur le compte. Le compte peut être bloqué ou ne pas disposer de fonds suffisants.
`missing-funds-reservation`	Les fonds réservés sont insuffisants.
`merchant-not-found`	Le marchand est introuvable.
`unsupported-command`	Commande non prise en charge.
`no_auth_required`	L’intention de paiement ne requiert pas d’authentification.
`transaction_canceled`	L’intention de paiement a été annulée. Aucun paiement ne peut être traité.
`transaction_missing`	La transaction (transfert ou paiement) est introuvable.
`transaction_in_progress`	La transaction (transfert ou paiement) est déjà en cours.
`transaction_done`	La transaction (transfert ou paiement) a déjà été effectuée.
`missing_permission`	La clé API ne dispose pas de la permission requise par le point de terminaison (HTTP `403`).
`wrong_provider`	L’opérateur n’existe pas pour le pays et le moyen de paiement de la requête (HTTP `400`). Utilisez `GET /data/providers` pour lister les opérateurs valides.
`instant_payment_not_enabled_for_merchant`	Le paiement instantané n’est pas activé pour le marchand (HTTP `403`). Contactez le support HUB2.
`instant_payment_live_only`	Les alias de paiement instantané ne se gèrent qu’en mode live (HTTP `403`).
`instant_payment_alias_not_owned`	L’alias de paiement instantané n’existe pas ou n’est pas enregistré pour le marchand (HTTP `403`).
`instant_payment_account_not_enrolled`	Le compte n’est pas encore enrôlé pour le paiement instantané (HTTP `409`). Contactez le support HUB2.
`instant_payment_primary_alias_protected`	L’alias est l’alias principal enregistré par HUB2 et ne peut pas être supprimé par l’API (HTTP `409`).
`instant_payment_alias_deactivated`	HUB2 a désactivé l’alias du compte. Seul le support HUB2 peut le rétablir (HTTP `409`).
`instant_payment_alias_refused`	L’annuaire du paiement instantané a refusé l’opération sur l’alias. Rien n’a été modifié (HTTP `422`).
`instant_payment_account_missing`	Le marchand n’a pas de compte live du type demandé (HTTP `422`).
`instant_payment_participant_not_served`	Le paiement instantané n’est pas disponible dans le pays du marchand (HTTP `422`).
`instant_payment_alias_not_recorded`	L’alias a été enregistré dans l’annuaire mais HUB2 n’a pas pu l’enregistrer. Relancez la requête (HTTP `502`).
`instant_payment_alias_deletion_not_recorded`	L’alias a été retiré de l’annuaire mais HUB2 n’a pas pu enregistrer le retrait. Relancez la requête (HTTP `502`).
`instant_payment_alias_divergence`	L’annuaire et HUB2 ne sont pas d’accord sur l’alias. Rien n’a été enregistré. Contactez le support HUB2 (HTTP `502`).
`instant_payment_alias_rail_unavailable`	L’annuaire du paiement instantané est indisponible. Réessayez plus tard (HTTP `503`).
`reference_required`	La `reference` du transfert est vide ou composée uniquement d’espaces (HTTP `400`). S’applique lorsque la protection contre les doublons est activée sur votre compte.
`duplicate_reference`	La `reference` est déjà utilisée par un transfert avec des informations différentes (HTTP `409`). Utilisez une nouvelle référence, ou renvoyez le transfert d’origine pour le récupérer. S’applique lorsque la protection contre les doublons est activée sur votre compte.
`possible_duplicate`	Un transfert avec les mêmes informations a été créé sous une autre référence il y a moins de 15 minutes : celui-ci n’a donc pas été créé (HTTP `409`). Le corps de l’erreur contient aussi `rejection_id` et `expires_at`, décrits ci-dessous. S’applique lorsque la protection contre les doublons est activée sur votre compte.
`invalid_duplicate_confirmation`	Le `rejectionId` envoyé ne peut pas confirmer ce transfert : il est inconnu, expiré ou déjà utilisé, ou le transfert diffère de celui qui a été refusé (HTTP `422`). Renvoyez le transfert sans `rejectionId`. S’applique lorsque la protection contre les doublons est activée sur votre compte.

Champs supplémentaires de `possible_duplicate`

Le corps d’une erreur possible_duplicate contient deux champs en plus du format habituel :

Nom du champ	Description
`rejection_id`	Identifiant à renvoyer dans `rejectionId`, avec le transfert inchangé, pour confirmer que le transfert est voulu.
`expires_at`	Date limite d’utilisation de `rejection_id`, au format ISO 8601 (15 minutes après le refus).

La protection contre les doublons n’est pas activée par défaut : contactez le support HUB2 pour l’activer. Voir Relancer un transfert en toute sécurité.

​Format des erreurs

​Exemple : erreur 404

​Codes d’erreur

​Codes de statut HTTP

​Codes d’erreur applicatifs

​Champs supplémentaires de possible_duplicate

Format des erreurs

Exemple : erreur 404

Codes d’erreur

Codes de statut HTTP

Codes d’erreur applicatifs

Champs supplémentaires de `possible_duplicate`