Fehlerreferenz

IBANforge verwendet standardmässige HTTP-Statuscodes und gibt strukturierte Fehler im JSON-Format zurück, {"error": "<token>", "message": "<text>"}. Verzweigen Sie auf error, das stabil bleibt; message kann umformuliert werden. Diese Seite behandelt die Statuscodes der API und die Codes, die ihre Routen teilen; ein Code, der nur zu einer Route gehört (API-Schlüssel, britische Institute), steht auf der Seite dieser Route.

Eine ungültige IBAN ist kein Fehlerstatus. POST /v1/iban/validate antwortet mit HTTP 200, valid: false, einem error-Code und einem Satz in error_detail. Nur die Anfrage selbst (ihr JSON, ein fehlendes Feld, Zahlung, Kontingent, Grösse, Rate) ändert den HTTP-Status.

HTTP-Statuscodes

Validierungsfehlercodes

Sie stehen im Body einer 200-Antwort, wenn valid den Wert false hat: Die Anfrage war erfolgreich, die IBAN hat die Prüfung nicht bestanden. POST /v1/iban/validate, jedes Element von POST /v1/iban/batch und die kostenlose Route GET /v1/iban/format verwenden dieselben sechs Codes. Eine Ausnahme auf /v1/iban/format: Eine Länge ausserhalb der Grenzen (weniger als 15 oder mehr als 34 Zeichen ohne Leerzeichen und Bindestriche, oder mehr als 64 wie gesendet) ergibt 400 invalid_iban_length, nicht 200.

Leerzeichen (geschützte eingeschlossen) und ASCII-Bindestriche werden entfernt und Buchstaben unabhängig von Gross- und Kleinschreibung gelesen, bevor eine dieser Prüfungen läuft.

Beispiel: Validierungsfehler

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

cost_usdc ist 0, wenn ein Schlüssel oder die Kostprobe ohne Schlüssel den Aufruf bedient hat, und der Preis der Route, wenn der Aufruf per x402 bezahlt wurde.

Eine leere oder fehlende IBAN

{"iban": ""} oder ein Body ganz ohne iban ist eine unvollständige Anfrage, keine ungültige IBAN. Mit einem Schlüssel lautet die Antwort 400 invalid_request. Ohne Schlüssel kommt der 402-Zahlungsumschlag, und von der Kostprobe ohne Schlüssel wird nichts verbraucht: Ein leeres {} ist die Sonde, mit der x402-Indexer die Route entdecken.

Anfragefehlercodes

Sie liefern einen anderen Status als 200.

400 Bad Request

Beispiel: Fehlerhafte Anfrage

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

402 Payment Required

Wird zurückgegeben, wenn eine kostenpflichtige Route ohne brauchbaren Zahlungsweg aufgerufen wird: weder Schlüssel noch verbleibendes Gratiskontingent, ein ungültiger Schlüssel oder einer, dessen Kontingent oder Guthaben verbraucht ist, oder eine gesendete und abgelehnte Zahlung. Der Body ist der x402-Zahlungsumschlag; der Header PAYMENT-SIGNATURE (x402 v2) oder X-PAYMENT (v1) begleicht ihn. Wenn ein genauer Grund zutrifft, trägt der Body zusätzlich cause.reason und eine message, die den Ausweg nennt:

{
  "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"
    }
  ]
}

Wurde eine Zahlung gesendet und abgelehnt, trägt der Body zusätzlich payment_error mit dem Grund.

Bei einem gültigen Schlüssel trägt der Body außerdem credit_packs.topup_this_key: die Kartenlinks und die USDC-Route, die den vorgelegten Schlüssel aufladen, damit das Guthaben auf ihm landet und sich an Ihrer Integration nichts ändert, und bei einem Schlüssel ohne Abonnement pro: der Link, der Pro auf genau diesen Schlüssel legt. pay_by_card behält seine Bedeutung: ein ohne Schlüssel gekauftes Paket, geliefert als neuer Schlüssel.

Wie Sie damit umgehen, steht unter x402-Zahlungen; den kostenlosen Schlüssel erklärt API-Schlüssel.

404 Not Found

Ein unbekannter Code ist kein 404: GET /v1/bic/{code} antwortet mit 200 und found: false, und GET /v1/ch/clearing/{iid} antwortet mit 200, found: false und error: "clearing_not_found".

405 Method Not Allowed

method_not_allowed: Der Pfad existiert, die Methode nicht. Das Feld allow listet die Methoden, die der Pfad annimmt. Der häufige Fall ist GET /v1/keys/generate: Ein Schlüssel wird mit einem POST geholt, und ganz ohne Body verlangt er keine E-Mail.

413 Payload Too Large

payload_too_large: Der Body der Anfrage ist grösser als 256 KB. Die Prüfung läuft vor dem Routing und vor der Zahlung, es wird also nichts berechnet. Ein Stapel von 100 IBANs wiegt etwa 5 KB.

429 Too Many Requests

rate_limit_exceeded: mehr als 100 Anfragen in einer Minute von derselben IP-Adresse. Die Antwort trägt einen Header Retry-After und ein Feld retry_after, beide in Sekunden. Jede gezählte Antwort trägt RateLimit-Limit, RateLimit-Remaining und RateLimit-Reset (Sekunden), dazu die älteren Header X-RateLimit-*, deren Reset ein Unix-Zeitstempel ist. /health, /ping, /openapi.json und /v1/demo werden nicht gezählt. Dasselbe Limit ist unter /.well-known/rate-limits.yml veröffentlicht.

Einen Schlüssel holen und beanspruchen haben eigene Tageslimits mit eigenen 429-Codes: siehe API-Schlüssel. Das Monatskontingent eines Schlüssels ist kein 429: Es endet mit dem 402 oben. Jede Antwort auf einen Monatsschlüssel (kostenlos oder beansprucht) trägt X-Quota-Used, X-Quota-Limit und X-Quota-Remaining (GET /v1/keys/usage liefert denselben Stand); ein Schlüssel mit Prepaid-Guthaben trägt X-Credits-Remaining und X-Credits-Total (GET /v1/credits/balance), und ein Schlüssel mit beidem trägt beide Reihen. Jede abgerechnete Antwort auf einen Schlüssel sagt in X-Charged-From, was sie bezahlt hat: allowance, credits oder allowance+credits für einen zwischen beiden aufgeteilten Batch.

500 Internal Server Error

Wenn Sie einen 500-Fehler erhalten, ist auf unserer Seite etwas Unerwartetes passiert. Der Body ist der reine Text Internal Server Error: Ein 500 hat keinen JSON-Umschlag. Bitte melden Sie ihn mit dem Endpunkt und der Uhrzeit des Aufrufs (UTC).

Fehlerbehebung

„Payment Required" bei jeder Anfrage

• Ohne Schlüssel hat nur POST /v1/iban/validate eine Kostprobe ohne Schlüssel (25 Aufrufe pro Woche und Quelladresse, Rücksetzung am Montag um 00:00 UTC). Jede andere kostenpflichtige Route braucht einen Schlüssel oder eine Zahlung
• Lesen Sie cause.reason im Body des 402, wenn es dort steht: Es nennt das verbrauchte Kontingent
• Für x402: Stellen Sie sicher, dass Sie USDC im Base-Netzwerk haben (nicht im Ethereum-Mainnet), dass der private Wallet-Schlüssel, den Ihr Client liest (zum Beispiel WALLET_PRIVATE_KEY), gesetzt ist und dass Sie ein kompatibles x402-Client-SDK verwenden

„Invalid IBAN format", obwohl die IBAN korrekt aussieht

• Nur die Buchstaben A-Z, die Ziffern 0-9, Leerzeichen und ASCII-Bindestriche werden angenommen; Punkte, Schrägstriche und typografische Striche werden abgelehnt
• Achten Sie auf weitere Nicht-ASCII-Zeichen (typografische Anführungszeichen, Leerzeichen ohne Breite)
• Gross- und Kleinschreibung spielen keine Rolle

„Unsupported country" für ein gültiges Land

• IBANforge unterstützt die 89 IBAN-Länder. Manche Gebiete verwenden die IBAN eines anderen Landes: Prüfen Sie, welches sie ausgibt
• Prüfen Sie den zweistelligen Ländercode am Anfang der IBAN

„BIC not found", obwohl der Code existiert

• Das BIC-Verzeichnis enthält über 121 000 Einträge aus öffentlichen Quellen (GLEIF, nationale Register wie die der Bundesbank, von SIX und der NBP, EBA STEP2 SCT sowie eine öffentliche Kopie des SWIFT-Verzeichnisses, eingefroren im Januar 2018), deckt aber nicht unbedingt jede Filiale ab
• Versuchen Sie die 8-stellige Version (ohne Filialcode), z. B. UBSWCHZH statt UBSWCHZH80A
• Einige Finanzinstitute verwenden BIC-Codes, die nicht bei SWIFT oder GLEIF registriert sind

Eine Stapelanfrage wird abgelehnt

• Über 100 Elemente wird der Stapel als Ganzes mit 400 batch_too_large abgelehnt: Teilen Sie die Liste auf
• Jedes Element muss ein String sein: Eine Zahl oder ein Objekt macht die ganze Anfrage zu 400 invalid_request
• Das Ergebnis-Array entspricht immer der Reihenfolge und Anzahl des Eingabe-Arrays

Zeitüberschreitung oder keine Antwort

• Ein Stapel von bis zu 100 IBANs ist eine einzige Anfrage und wird in einem Stück beantwortet
• Überprüfen Sie Ihre Netzwerkverbindung und Firewall-Regeln
• Testen Sie den kostenlosen Endpunkt /health, um zu prüfen, ob der Dienst läuft, und die Statusseite für die aktuelle Verfügbarkeit

Support

• Schreiben Sie an support@ibanforge.com mit dem Endpunkt, der Uhrzeit des Aufrufs (UTC) und Ihrem key_prefix, nie mit dem Schlüssel selbst
• Öffentliche Fragen und Fehlerberichte: GitHub Issues
• Von einem Agenten aus: POST /v1/feedback oder das MCP-Tool send_feedback, kostenlos und ohne Schlüssel
• Aktuelle Verfügbarkeit: die Statusseite. Ein schriftliches SLA gibt es nur für Editor/OEM-Abonnements: SLA