Codes d'Erreur

Format de l'erreur

Toute erreur /v1 a la même forme, avec le statut HTTP des tableaux ci-dessous. Comparez error.code, qui est un snake_case stable. error.message est un texte libre en anglais pour vos logs. error.details n'apparaît que s'il y a des données utiles, comme des champs invalides, des limites ou des scopes.

{
  "error": {
    "code": "insufficient_total_balance",
    "message": "Insufficient balance to cover all payouts",
    "details": {
      "crypto_currency": "USDT",
      "available": "150.00000000",
      "required": "420.50000000"
    }
  }
}

Dans un lot POST /v1/payout, chaque élément refusé porte le même objet dans results[].error, à côté de son index et de son reference_id. La réponse est 200 quand tous les éléments ont réussi, 207 quand certains ont réussi et d'autres échoué, et 400 quand aucun n'a réussi :

{
  "message": "payment_processing_completed",
  "summary": {
    "total_requested": 3,
    "successful": 1,
    "failed": 2
  },
  "results": [
    {
      "index": 0,
      "reference_id": "order_1001",
      "internal_reference": "BIFROST_REF_123456",
      "status": "created"
    },
    {
      "index": 1,
      "reference_id": "order_1002",
      "error": {
        "code": "invalid_parameters",
        "message": "Invalid parameters provided",
        "details": {
          "fields": {
            "wallet": "Invalid wallet format"
          }
        }
      }
    },
    {
      "index": 2,
      "reference_id": "order_1003",
      "error": {
        "code": "daily_payout_limit_exceeded",
        "message": "Daily payout limit for this API key exceeded"
      }
    }
  ]
}

• Les messages de validation se trouvent toujours dans error.details.fields, indexés par nom de champ, au premier niveau comme dans un élément du lot.
• Un élément de payout en double compte comme un échec : il porte error.code duplicate_payment_reference ainsi que duplicate, original_status et original_created_at dans l'élément. Un lot composé uniquement de doublons répond 400.
• Décidez selon error.code, jamais selon error.message : les messages peuvent être reformulés, les codes ne changent pas.
• 4xx signifie que la requête doit être modifiée avant d'être renvoyée. 5xx signifie que l'échec vient de notre côté et que la même requête peut être réessayée ; sur POST /v1/payout, le reference_id vous protège toujours d'un double retrait.
• Un chemin /v1 inconnu renvoie 404 route_not_found en JSON. Un client qui demande text/html dans Accept reçoit une page HTML.

Erreurs d'Authentification et d'Accès

Erreurs de Requête

Erreurs Métier

Erreurs par Élément du Lot de Payout (results[].error)

Erreurs Système

Meilleures Pratiques