Erreurs

Toute erreur de l’API 221 (221 Pay, routes de données, routes de projet, 404 et 405 compris) a la même enveloppe : un code stable à tester dans le code, un message lisible, un request_id à transmettre au support, fields quand des champs sont refusés, et des membres propres au code (limit, reset_at, retry_after_s…), au même niveau.

{
  "code": "INVALID_REQUEST",
  "message": "Certains champs sont invalides.",
  "request_id": "2f6c9a0e-5b1d-4e7f-8c3a-9d0b1e2f3a4c",
  "fields": {
    "customer_phone": "Numéro mobile invalide pour le pays de ce moyen de paiement.",
    "offer_code": "offer_code doit contenir de 4 à 16 lettres ou chiffres."
  }
}

• Tester code, jamais message ni le statut HTTP : le texte peut changer, et un même code peut porter un statut différent selon la route.
• fields regroupe un message par champ refusé, pour afficher chaque erreur à côté de son champ.
• message est en français ; en anglais avec Accept-Language: en ou le paramètre ?lang=en.
• request_id est aussi renvoyé dans l’en-tête X-Request-Id de chaque réponse.

Limite de requêtesCopier le lien de la section

600 requêtes par minute et par projet. Au-delà : 429 RATE_LIMITED, avec l’en-tête Retry-After, le délai d’attente en secondes.

HTTP/1.1 429 Too Many Requests
Retry-After: 12

C’est la seule limite des routes 221 Pay : le quota quotidien (429 QUOTA_EXCEEDED) ne concerne que les routes de données. Voir Authentification, section « Quota quotidien ».

Méthode non autoriséeCopier le lien de la section

Une route de /v1 appelée avec une autre méthode HTTP répond 405 avec l’en-tête Allow, la liste des méthodes acceptées, et la même enveloppe que les autres erreurs, avec le code METHOD_NOT_ALLOWED. Le message suit Accept-Language (français par défaut, anglais si la valeur commence par en).

HTTP/1.1 405 Method Not Allowed
Allow: GET, POST
Content-Type: application/json

{"code": "METHOD_NOT_ALLOWED", "message": "Méthode non autorisée. Méthodes acceptées : GET, POST.", "request_id": "2f6c9a0e-5b1d-4e7f-8c3a-9d0b1e2f3a4c"}

CodesCopier le lien de la section

Codes des routes de données et de projetCopier le lien de la section

Ces codes, écrits en majuscules comme les autres, viennent des routes de données, des clés, des webhooks et de l’équipe d’un projet. Les membres propres au code sont au premier niveau du corps, à côté de message. Le statut HTTP peut varier selon la route : tester code.

Les routes /auth (connexion, mot de passe) répondent aussi avec une forme plate code, message et request_id (aussi dans l’en-tête X-Request-Id). Leurs codes sont ceux du service de connexion, par exemple INVALID_EMAIL, INVALID_EMAIL_OR_PASSWORD ou VALIDATION_ERROR (corps illisible, avec un seul message générique). TOO_MANY_REQUESTS ajoute retry_after_s et l’en-tête X-Retry-After.

Réessayer sans risqueCopier le lien de la section

POST /v1/payments, POST /v1/refunds et POST /v1/payouts exigent Idempotency-Key : un réessai ne crée jamais une seconde opération. Voir Paiements, section « Issue inconnue ».

Signaler un incidentCopier le lien de la section

Transmettre à 221 le request_id, l’heure de l’appel et la route appelée. Jamais la clé API ni le secret de webhook.