Référence des erreurs

IBANforge utilise les codes de statut HTTP standards et renvoie des erreurs structurées en JSON, {"error": "<jeton>", "message": "<phrase>"}. Aiguillez sur error, qui est stable ; message peut être reformulé. Cette page couvre les statuts de l'API et les codes que ses routes partagent ; un code propre à une seule route (clés API, établissements britanniques) figure sur la page de cette route.

Un IBAN invalide n'est pas un statut d'erreur. POST /v1/iban/validate répond HTTP 200 avec valid: false, un code error et une phrase error_detail. Seule la requête elle-même (son JSON, un champ manquant, le paiement, le quota, la taille, le débit) change le statut HTTP.

Codes de statut HTTP

Codes d'erreur de validation

Ils apparaissent dans le corps d'une réponse 200 quand valid vaut false : la requête a réussi, l'IBAN n'a pas passé. POST /v1/iban/validate, chaque élément de POST /v1/iban/batch et la route gratuite GET /v1/iban/format emploient les mêmes six codes. Une exception sur /v1/iban/format : une longueur hors bornes (moins de 15 ou plus de 34 caractères une fois les espaces et traits d'union retirés, ou plus de 64 tels qu'envoyés) répond 400 invalid_iban_length, et non 200.

Les espaces (insécables compris) et les traits d'union ASCII sont retirés, et les lettres lues sans égard à la casse, avant tous ces contrôles.

Exemple : erreur de validation

{
  "iban": "CH100023000000001234",
  "valid": false,
  "error": "wrong_length",
  "error_detail": "Expected 21 characters for CH, got 20.",
  "cost_usdc": 0
}

cost_usdc vaut 0 quand une clé ou l'essai sans clé a servi l'appel, et le prix de la route quand l'appel a été payé par x402.

Un IBAN vide ou absent

{"iban": ""}, ou un corps sans iban, est une requête incomplète plutôt qu'un IBAN invalide. Avec une clé, la réponse est 400 invalid_request. Sans clé, c'est l'enveloppe de paiement 402, et rien n'est pris sur l'essai sans clé : un {} vide est la sonde par laquelle les indexeurs x402 découvrent la route.

Codes d'erreur de requête

Ils renvoient un statut autre que 200.

400 Bad Request

Exemple : requête incorrecte

{
  "error": "batch_too_large",
  "message": "Maximum 100 IBANs per batch request"
}

402 Payment Required

Renvoyé quand une route payante est appelée sans moyen de payer utilisable : ni clé ni franchise gratuite restante, une clé invalide ou dont la franchise ou les crédits sont épuisés, ou un paiement envoyé puis refusé. Le corps est l'enveloppe de paiement x402 ; l'en-tête PAYMENT-SIGNATURE (x402 v2) ou X-PAYMENT (v1) la règle. Quand une raison précise s'applique, le corps porte aussi cause.reason et un message qui nomme la sortie :

{
  "x402Version": 2,
  "error": "payment_required",
  "resource": { "url": "https://api.ibanforge.com/v1/iban/validate" },
  "accepts": [
    {
      "scheme": "exact",
      "network": "eip155:8453",
      "amount": "5000",
      "payTo": "0x...",
      "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"
    }
  ]
}

Quand un paiement a été envoyé et refusé, le corps porte aussi payment_error avec la raison.

Sur une clé valide, le corps porte aussi credit_packs.topup_this_key : les liens de paiement par carte et la route USDC qui rechargent la clé présentée, pour que les crédits arrivent sur elle et que rien ne change dans votre intégration, et, sur une clé sans abonnement, pro : le lien qui pose Pro sur cette même clé. pay_by_card garde son sens : un pack acheté sans clé, livré comme une clé neuve.

Consultez Paiements x402 pour savoir comment gérer cela, et Clés API pour la clé gratuite.

404 Not Found

Un code inconnu n'est pas un 404 : GET /v1/bic/{code} répond 200 avec found: false, et GET /v1/ch/clearing/{iid} répond 200 avec found: false et error: "clearing_not_found".

405 Method Not Allowed

method_not_allowed : le chemin existe, pas la méthode. Le champ allow liste les méthodes que le chemin accepte. Le cas courant est GET /v1/keys/generate : une clé se prend par un POST, et sans aucun corps elle ne demande pas d'e-mail.

413 Payload Too Large

payload_too_large : le corps de la requête dépasse 256 Ko. Le contrôle a lieu avant le routage et avant le paiement, donc rien n'est facturé. Un lot de 100 IBAN pèse environ 5 Ko.

429 Too Many Requests

rate_limit_exceeded : plus de 100 requêtes en une minute depuis la même adresse IP. La réponse porte un en-tête Retry-After et un champ retry_after, tous deux en secondes. Chaque réponse décomptée porte RateLimit-Limit, RateLimit-Remaining et RateLimit-Reset (en secondes), plus les anciens en-têtes X-RateLimit-*, dont la remise à zéro est un horodatage Unix. /health, /ping, /openapi.json et /v1/demo ne sont pas décomptés. La même limite est publiée dans /.well-known/rate-limits.yml.

Prendre et réclamer une clé ont leurs propres limites du jour, avec leurs propres codes 429 : voir Clés API. Le quota du mois d'une clé n'est pas un 429 : il se termine par le 402 ci-dessus. Chaque réponse servie sur une clé mensuelle (gratuite ou réclamée) porte X-Quota-Used, X-Quota-Limit et X-Quota-Remaining (GET /v1/keys/usage rend le même décompte) ; une clé qui a des crédits prépayés porte X-Credits-Remaining et X-Credits-Total (GET /v1/credits/balance), et une clé qui a les deux porte les deux séries. Chaque réponse facturée sur une clé dit qui l'a payée dans X-Charged-From : allowance, credits, ou allowance+credits pour un lot partagé entre les deux.

500 Internal Server Error

Si vous recevez une erreur 500, quelque chose d'inattendu s'est produit de notre côté. Le corps est le texte brut Internal Server Error : un 500 n'a pas d'enveloppe JSON. Signalez-le avec l'endpoint et l'heure de l'appel (UTC).

Dépannage

« Payment Required » à chaque requête

• Sans clé, seule POST /v1/iban/validate a un essai sans clé (25 appels par semaine et par adresse source, remis à zéro le lundi à 00:00 UTC). Toute autre route payante demande une clé ou un paiement
• Lisez cause.reason dans le corps du 402 quand il y figure : il nomme la franchise épuisée
• Pour x402 : assurez-vous d'avoir des USDC sur le réseau Base (et non sur le mainnet Ethereum), que la clé privée du portefeuille que lit votre client (par exemple WALLET_PRIVATE_KEY) est définie, et que vous utilisez un SDK client x402 compatible

« Invalid IBAN format » alors que l'IBAN semble correct

• Seuls les lettres A-Z, les chiffres 0-9, les espaces et les traits d'union ASCII sont acceptés ; points, barres obliques et tirets typographiques sont refusés
• Vérifiez qu'il n'y a pas d'autre caractère non ASCII (guillemets typographiques, espaces de largeur nulle)
• La casse n'a pas d'importance

« Unsupported country » pour un pays valide

• IBANforge prend en charge les 89 pays de l'IBAN. Certains territoires utilisent l'IBAN d'un autre pays : vérifiez lequel l'émet
• Vérifiez le code pays à deux lettres au début de l'IBAN

« BIC not found » alors que le code est réel

• L'annuaire BIC compte plus de 121 000 entrées issues de sources publiques (GLEIF, registres nationaux comme ceux de la Bundesbank, de SIX et de la NBP, EBA STEP2 SCT, et une copie publique de l'annuaire SWIFT figée en janvier 2018), mais peut ne pas couvrir toutes les agences
• Essayez la version à 8 caractères (sans code agence), par ex. UBSWCHZH au lieu de UBSWCHZH80A
• Certains établissements financiers utilisent des codes BIC qui ne sont pas enregistrés auprès de SWIFT ou de GLEIF

Une requête de lot est refusée

• Au-delà de 100 éléments, le lot est refusé en bloc avec 400 batch_too_large : découpez la liste
• Chaque élément doit être une chaîne : un nombre ou un objet rend toute la requête 400 invalid_request
• Le tableau de résultats suit toujours l'ordre et le nombre du tableau d'entrée

Délai dépassé ou absence de réponse

• Un lot de 100 IBAN au plus est une seule requête, qui reçoit sa réponse d'un bloc
• Vérifiez votre connexion réseau et les règles de pare-feu
• Essayez l'endpoint gratuit /health pour vérifier que le service fonctionne, et la page de statut pour la disponibilité en direct

Support

• Écrivez à support@ibanforge.com avec l'endpoint, l'heure de l'appel (UTC) et votre key_prefix, jamais la clé elle-même
• Questions publiques et signalements de bogues : GitHub Issues
• Depuis un agent : POST /v1/feedback ou l'outil MCP send_feedback, gratuits et sans clé
• Disponibilité en direct : la page de statut. Un SLA écrit existe pour les abonnements Editor/OEM seulement : SLA