Diagnostiquez à partir du statut et du code stable
Conservez X-Request-Id, l’identifiant d’opération et le statut. Ne journalisez jamais la clé API, l’URL destinataire, le contact, l’image de preuve ou le corps brut du webhook. Certains points de terminaison renvoient un code structuré ; d’autres renvoient des erreurs de validation ou une réponse 401/403/404 vide. Ne supposez pas que toutes les erreurs ont la même structure JSON et ne fondez jamais la logique sur le texte traduit d’un message.
| Code ou statut | Cause probable | Nouvelle tentative et correction |
|---|---|---|
| 401 | Identifiant absent, mal formé, révoqué ou expiré | Corriger l’identifiant ; ne pas réessayer sans changement |
| 403 | Portée ou permission du compte manquante | Vérifier la portée de l’opération et l’environnement ; actualiser les identifiants après modification de la configuration |
| 404 | Mauvais identifiant ou environnement, ou lien d’accès expiré/invalide | Vérifier la lecture authentifiée de la ressource de référence et l’environnement |
| 429 | Limite de débit ou quota | Respecter Retry-After ; délai exponentiel avec variation aléatoire |
| 5xx / erreur de transport | Erreur temporaire du service ou du réseau | Réutiliser exactement les identifiants et le corps, limiter les tentatives et consulter l’état de référence si le résultat est incertain |
returns_paused | Écritures de retours temporairement indisponibles | Réessayer plus tard avec les mêmes identifiants ; les lectures restent disponibles |
idempotency_key_invalid | Clé de création absente ou trop longue | Fournir une clé stable non vide, de 160 caractères au maximum |
idempotency_conflict | Clé réutilisée pour une autre opération | Récupérer la requête d’origine ou utiliser une clé pour une opération réellement nouvelle |
event_id_invalid | UUID absent ou vide | Générer et conserver un UUID par événement |
occurred_at_invalid | Date d’événement dans le futur | Corriger l’horloge ou l’horodatage ; conserver l’heure réelle de survenue |
return_not_eligible | État de livraison incompatible avec ce type de retour | Le retour client exige Delivered ; le RTS après échec exige DeliveryAttempted |
return_state_conflict | Transition invalide, dépendance à une preuve ou événement contradictoire | Lire l’état de référence et les exigences de preuve ; corriger avant de réessayer |
return_conflict | Retour concurrent ou contrainte d’identifiant | Lire le retour actuel ; ne pas créer de travail physique en double |
return_origin_invalid, return_destination_invalid | Instantané absent ou invalide | Fournir des champs d’adresse confirmée et des coordonnées valides |
return_event_invalid | Données d’événement invalides | Corriger les données selon la référence API |
return_pickup_confirmation_not_allowed | Accès à la collecte interdit dans l’état actuel | Examiner l’état d’autorisation et de remise avant d’émettre un nouveau lien |
return_proof_asset_missing | Référence ne correspondant pas à un fichier de retour téléversé | Téléverser d’abord le PNG avec le retour, la preuve et le type correspondants ; utiliser la référence renvoyée |
return_proof_invalid, proof_image_invalid | Image ou champs de preuve invalides | Corriger la méthode, l’usage, les dimensions, la taille et l’horodatage |
return_proof_conflict | UUID de preuve réutilisé avec un autre contenu | Réessayer avec une preuve identique ; ne jamais écraser une preuve immuable |
return_destination_required | Politique RTS exigeant une destination | Fournir la destination convenue de l’expéditeur ou du commerçant |
Problèmes d’intégration courants
La clé copiée commence par [object Object] : recopiez l’identifiant depuis la console. Une clé ne contient ni icône, ni balisage, ni texte d’affichage ajouté. Configurez sa valeur brute complète.
Le statut de livraison n’a pas avancé après l’envoi de la preuve : vérifiez la synchronisation de la preuve. La portée delivery:proof est distincte de delivery:events. L’échec d’une preuve bloque l’événement de finalisation qui en dépend. Corrigez la configuration et réessayez l’opération d’origine avec les mêmes identifiants.
Mon e-mail correspond, mais le lien destinataire ne fonctionne pas : vérifiez que le contact de référence de l’expédition est correct et que le contact du compte est vérifié. Un contact utilisé uniquement pour confirmer l’adresse ne change pas l’appartenance de l’expédition. Le suivi public renseigne sur l’avancement, pas sur l’autorisation du destinataire.
Aucune option de retour n’est disponible : la livraison doit être liée et son état de référence doit être Delivered avant qu’un retour client puisse commencer.
L’URL de preuve de retour est rejetée : téléversez un véritable PNG via l’API des fichiers de retour. Une signature textuelle ou une URL arbitraire du commerçant ne satisfait pas ce contrat.
La signature du webhook échoue : préservez les octets bruts, vérifiez le secret du bon abonnement, contrôlez la fraîcheur de l’horodatage et évitez toute resérialisation JSON. Consultez les recettes de webhooks.