# Fehlerreferenz

> Source: https://docs.blockvectra.com/de/errors/

Diese Referenz dokumentiert alle Fehlercodes und maschinenlesbaren `reason`-Werte über alle BlockVectra-Dienste hinweg, einschließlich der Information, ob ein abgewiesener Aufruf abgerechnet wird, Wiederholungsrichtlinien, Backoff-Dauern und empfohlener Maßnahmen für KI-Agenten und automatisierte Clients.

Für maschinenlesbare Verarbeitung rufen Sie den vollständigen Katalog als JSON unter [/errors.json](https://docs.blockvectra.com/errors.json) ab. Jede Fehlerantwort mit einer `docs_url` verweist direkt auf einen stabilen Anker auf dieser Seite: `https://docs.blockvectra.com/en/errors/#<reason>` (oder `#-<code-number>` für Fehler ohne `reason`-Code).

### JSON-RPC-Fehler



| HTTP | Code | Reason | Bedeutung | Berechnet | Wiederholbar | Wartezeit (Retry-After) | Agent-Aktion |
| --- | --- | --- | --- | --- | --- | --- | --- |
| 401 | -32024 | `missing_api_key` | `Fehlender API-Schlüssel: Bitte im Anfragepfad (/v1/{chain}/<api_key>) oder im x-api-key-Header übergeben` | Nein | Nein | — | Für JSON-RPC-Endpunkte (/v1/{chain}) den API-Schlüssel im Anfragepfad (/v1/{chain}/<api_key>) oder im x-api-key-Header bereitstellen. Für die Top-up API (/v1/topup/*) den API-Schlüssel nur im x-api-key-Header bereitstellen. |
| 401 | -32024 | `invalid_api_key` | `Unbekannter, deaktivierter oder widerrufener API-Schlüssel: JSON-RPC und Data API geben beide HTTP 401 mit einer invalid_api_key-Fehlerstruktur zurück (JSON-RPC: error.code -32024 und error.data.reason invalid_api_key; Data API: error.code und error.data.reason invalid_api_key).` | Nein | Nein | — | API-Schlüssel prüfen; falls erforderlich, erneut in der Konsole oder über die programmatische Registrierung anmelden, um einen neuen Schlüssel zu erstellen (siehe [Sitzung oder API-Schlüssel verloren?](https://docs.blockvectra.com/en/guides/programmatic-signup/#lost-your-session-or-api-key)). |
| 403 | -32025 | `key_expired` | `API-Schlüssel abgelaufen; neuen Schlüssel in der Konsole erstellen` | Nein | Nein | — | API-Schlüssel abgelaufen; neuen Schlüssel in der Konsole oder über die programmatische Registrierung erstellen. |
| 403 | -32025 | `key_cap_exhausted` | `Lebenslanges CU-Limit des API-Schlüssels aufgebraucht; neuen Schlüssel in der Konsole erstellen` | Nein | Nein | — | Lebenslanges CU-Limit des API-Schlüssels aufgebraucht; neuen Schlüssel in der Konsole oder über die programmatische Registrierung erstellen. |
| 503 | -32021 | `auth_unavailable` | `Authentifizierungsdaten vorübergehend nicht verfügbar` | Nein | Ja | Retry-After-Header (Sekunden) beachten | Server kann Schlüssel vorübergehend nicht verifizieren; dies ist kein Problem mit Ihrem Schlüssel. Nach Wartezeit gemäß Retry-After wiederholen; **den Schlüssel nicht neu erstellen**. |
| 404 | -32600 | `unknown_chain` | `Unbekannte Chain` | Nein | Nein | — | Verfügbare Chains über GET /v1/chains oder das Tool list_chains prüfen; URL-Pfad überprüfen. |
| 404 | 404 | `unknown_endpoint` | `Data-API-Methode und Pfad stimmen mit keiner bekannten Operation überein` | Nein | Nein | — | Methode und URL-Pfad anhand der Data-API-Dokumentation überprüfen. |
| 200 | -32700 | `parse_error` | `JSON-Parsing-Fehler` | Nein | Nein | — | Gültige JSON-Syntax im Anfragetext vor dem Senden sicherstellen. |
| 200 | -32600 | `invalid_request` | `Ungültige Anfrage` | Nein | Nein | — | Anfragestruktur prüfen; Felder jsonrpc: '2.0', id und method vor erneutem Senden verifizieren. |
| 200 | -32602 | `invalid_params` | `Tracer nicht zulässig` | Nein | Nein | — | Methodenparameter anpassen; unterstützte Tracer und Timeout-Limits für die Chain prüfen. |
| 200 | -32602 | `logs_range_too_large` | `Blockbereich für eth_getLogs zu groß: maximal <N> Blöcke` | Nein | Nein | — | Blockbereich der Abfrage auf das in GET /v1/chains angegebene max_logs_block_range eingrenzen. |
| 429 | -32005 | `public_rate_limit` | `Ratenlimit für öffentliche Anfragen überschritten` | Nein | Ja | Retry-After-Header (Sekunden) beachten | Gemäß Retry-After-Header warten und wiederholen; oder Anfrage mit einem API-Schlüssel senden. [API-Schlüssel anfordern](https://blockvectra.com/en/get-api-key/?ref=err-public). |
| 429 | -32005 | `public_pool_busy` | `Öffentlicher Chain-Pool ist ausgelastet` | Nein | Ja | Retry-After-Header beachten oder einige Sekunden warten und mit Backoff wiederholen | Mit Backoff wiederholen oder Anfrage mit einem API-Schlüssel senden. [API-Schlüssel anfordern](https://blockvectra.com/en/get-api-key/?ref=err-public). |
| 200 | -32601 | `method_not_public` | `Methode am öffentlichen Endpunkt nicht verfügbar` | Nein | Nein | — | Eine vom öffentlichen Endpunkt unterstützte Methode verwenden oder Anfrage mit einem API-Schlüssel senden. [API-Schlüssel anfordern](https://blockvectra.com/en/get-api-key/?ref=err-public). |
| 200 | -32601 | `method_not_allowed` | `Methode auf dieser Chain nicht verfügbar oder durch Richtlinie deaktiviert` | Nein | Nein | — | methods.allow und methods.deny in GET /v1/chains auf unterstützte Methoden prüfen. Die Unterstützung für das Senden von Transaktionen wird durch methods.allow in GET /v1/chains bestimmt. Das Senden von Transaktionen ist derzeit nicht verfügbar auf: HyperEVM. |
| 200 | -32601 | `subscription_not_available` | `WebSocket-Abonnement wird auf dieser Chain nicht angeboten` | Nein | Nein | — | Verfügbare Abonnements für diese Chain über GET /v1/chains prüfen. |
| 200 | -32602 | `logs_filter_required` | `Logs-Abonnement erfordert eine Adresse oder topic0 (ein Wert ungleich null an erster Topic-Position)` | Nein | Nein | — | Adresse oder ein topic0 ungleich null im Logs-Filter angeben. |
| 200 | -32600 | `batch_too_large` | `Batch zu groß: maximal <N> Aufrufe` | Nein | Nein | — | Batch in kleinere Batches aufteilen, die dem in den Fehlerdaten angegebenen maximalen Aufruflimit entsprechen. |
| 413 | 413 | `request_too_large` | `Anfragetext der Data API überschreitet das Größenlimit` | Nein | Nein | — | Größe des Anfragetexts verringern. |
| 200 | -32000 | `not_found` | `Transaktion nicht gefunden` | Nein | Nein | — | Falls kürzlich übermittelt oder gemint, Netzwerkweiterleitung abwarten und wiederholen; andernfalls Blocknummer oder Hash prüfen. |
| 200 | -32011 | `state_window` | `Historischer Status außerhalb der letzten <N> Blöcke nicht verfügbar` | Nein | Nein | — | Blöcke innerhalb von state_window_blocks gemäß GET /v1/chains abfragen oder Data API für historische Daten nutzen. |
| 200 | -32011 | `range_not_indexed` | `Angeforderter Verlauf ist noch nicht vollständig indexiert` | Nein | Nein | — | Angeforderten Verlauf auf einen indexierten Bereich eingrenzen; denselben nicht abgedeckten Bereich nicht unverändert wiederholen. |
| 200 | -32011 | `history_not_ready` | `Angeforderter Verlauf ist noch nicht bereit` | Nein | Ja | Warten, bis die Indexierung aufholt; error.data.retry_after_seconds beachten, sofern vorhanden | Wiederholen, sobald die Indexierung aufgeholt hat; angegebene Sekunden in error.data.retry_after_seconds abwarten. |
| 429 | -32005 | `key_rate_limit` | `CU-Ratenlimit des API-Schlüssels überschritten` | Nein | Ja | Retry-After-Header (Sekunden) beachten | Die im Retry-After-Header angegebene Dauer warten, bevor wiederholt wird, oder Last verteilen. |
| 429 | rate_limited | `rate_limited` | `Ratenlimit für Anfragen an die API oder GET /v1/account überschritten (mehr als 5 Anfragen pro Sekunde für diesen Schlüssel)` | Nein | Ja | Retry-After-Header (Sekunden) beachten | Den im Retry-After angegebenen Zeitraum warten, bevor wiederholt wird. |
| 429 | -32005 | `concurrency_limit` | `Limit für gleichzeitige Anfragen überschritten` | Nein | Ja | Retry-After-Header beachten oder auf den Abschluss aktiver Aufrufe warten | Client-Parallelitätspool verkleinern und wiederholen, sobald Plätze frei werden. |
| 429 | -32005 | `free_plan_call_limit` | `Limit für Aufrufe pro Sekunde im kostenlosen Tarif überschritten` | Nein | Ja | 1 Sekunde vor Wiederholung warten | Anfragerate drosseln oder aufladen, um Durchsatz der kostenpflichtigen Stufe freizuschalten. |
| 429 | -32022 | `request_exceeds_burst` | `Anfragekosten von <N> CU übersteigen die Burst-Kapazität von <M> CU` | Nein | Nein | — | Warten wird das Problem nicht lösen; Batch aufteilen oder Methodenparameter verringern, um innerhalb der Burst-Kapazität zu bleiben. |
| 429 | -32022 | `free_plan_batch_too_large` | `Anfrage umfasst <N> Aufrufe und überschreitet das Limit des kostenlosen Tarifs von <M> Aufrufen pro Sekunde` | Nein | Nein | — | Warten wird das Problem nicht lösen; Batch so aufteilen, dass die Aufrufanzahl im Limit des kostenlosen Tarifs liegt, oder aufladen. |
| 429 | -32005 | `ws_connection_limit` | `WebSocket-Verbindungslimit für diesen Schlüssel oder dieses Konto erreicht` | Nein | Nein | — | Ungenutzte WebSocket-Verbindung schließen oder bestehende Verbindung wiederverwenden. |
| 200 | -32022 | `subscription_limit` | `WebSocket-Abonnementlimit für diese Verbindung erreicht` | Nein | Nein | — | Ein bestehendes Abonnement kündigen oder eine andere Verbindung öffnen. |
| 200 | -32005 | `ws_filter_capacity` | `Kapazität der WebSocket-Logs-Filter ist erschöpft` | Nein | Nein | — | Bestehendes Logs-Abonnement kündigen oder einen engeren Filter verwenden. |
| 200 | -32026 | `ws_push_overloaded` | `WebSocket-Benachrichtigungswarteschlange ist überlastet` | Nein | Ja | Später mit Backoff wiederholen oder neu verbinden | eth_subscribe mit exponentiellem Backoff wiederholen oder neu verbinden. Bestehende Abonnements empfangen weiterhin Benachrichtigungen. |
| 200 | -32005 | `overloaded` | `Dienst vorübergehend überlastet, bitte später erneut versuchen` | Nein | Ja | Einige Sekunden warten und mit exponentiellem Backoff wiederholen | Backoff mit Jitter anwenden und Anfrage wiederholen. |
| 402 | -32020 | `balance_exhausted` | `Unzureichendes Guthaben (wenn Guthaben bekannt ist, enthält error.data balance_units und balance_cu)` | Nein | Nein | — | On-Chain aufladen: Einzahlungsadresse in der Konsole oder über `GET /v1/topup/deposit-address` abrufen (MCP `get_deposit_address`); siehe [Leitfaden zur Aufladung für Agenten](https://docs.blockvectra.com/en/guides/agent-topup/) oder Kontingent in der Konsole zurücksetzen, falls berechtigt. Wenn Guthaben bekannt ist, enthält error.data balance_units (bei Überziehung negativ) und balance_cu. |
| 402 | -32020 | `free_grant_exhausted` | `Freikontingent aufgebraucht (wenn Guthaben bekannt ist, enthält error.data balance_units und balance_cu)` | Nein | Nein | — | On-Chain aufladen: Einzahlungsadresse in der Konsole oder über `GET /v1/topup/deposit-address` abrufen (MCP `get_deposit_address`); siehe [Leitfaden zur Aufladung für Agenten](https://docs.blockvectra.com/en/guides/agent-topup/), Kontingentrücksetzung nutzen, falls verfügbar, oder auf das Kontingent des nächsten Zyklus warten. Wenn Guthaben bekannt ist, enthält error.data balance_units (bei Überziehung negativ) und balance_cu. |
| 503 | -32021 | `billing_unavailable` | `Abrechnungsdaten vorübergehend nicht verfügbar` | Nein | Ja | Retry-After-Header (Sekunden) beachten | Dies ist kein Guthabenproblem; neu erstellte Schlüssel synchronisieren sich innerhalb von Sekunden. Gemäß Retry-After warten und wiederholen. |
| 200 | -32010 | `node_syncing` | `Node synchronisiert; Aufrufe vorübergehend nicht verfügbar` | Nein | Ja | Einige Sekunden warten und wiederholen | Warten, bis Node-Synchronisation abgeschlossen ist, oder GET /v1/status prüfen. |
| 200 | -32603 | `upstream_unavailable` | `Upstream-Dienst nicht verfügbar` | Nein | Ja | Einige Sekunden warten und wiederholen | Mit exponentiellem Backoff wiederholen; GET /v1/status zur Überprüfung des Node-Zustands abfragen. |
| 504 | 504 | `upstream_timeout` | `Upstream-Dienst hat nicht innerhalb des Zeitlimits geantwortet` | Nein | Ja | Nach kurzer Verzögerung wiederholen | Anfrage mit exponentiellem Backoff wiederholen. |
| 200 | -32000 | `response_too_large` | `Upstream-Antwort zu groß` | Nein | Nein | — | Abfrageparameter eingrenzen (z. B. Blockbereich in eth_getLogs verkleinern oder kleinere Traces anfordern). |
| 200 | -32603 | `internal_error` | `Interner Dienstfehler` | Nein | Nein | — | Anfrage wiederholen; bei anhaltenden Fehlern mit Zeitstempel an den Support wenden. |
| 200 | 4444 | — | `Bereinigter Verlauf nicht verfügbar` | Nein | Nein | — | Block liegt außerhalb des vom bereinigten Node vorgehaltenen Verlaufsfensters; historische Blöcke über Data API abfragen. |
| 200 | -32000 | — | `Historischer Zustand nicht verfügbar; alte Daten aufgrund von Bereinigung nicht verfügbar` | Nein | Nein | — | Blöcke innerhalb des Zustandsfensters abfragen oder Data API für historische Abfragen nutzen. |
| 200 | -32002 | — | `<node message>` | Nein | Ja | Einige Sekunden warten und mit kleinerem Batch wiederholen | Anzahl der Aufrufe im Batch reduzieren und wiederholen. |
| 200 | -32003 | — | `<node message>` | Nein | Nein | — | Batch in kleinere Anfragen aufteilen, um die Größe der Antwortdaten zu reduzieren. |
| 200 | -32601 | — | `<node message>` | Nein | Nein | — | methods.allow und methods.deny in GET /v1/chains auf unterstützte Methoden prüfen. Die Unterstützung für das Senden von Transaktionen wird durch methods.allow in GET /v1/chains bestimmt. Das Senden von Transaktionen ist derzeit nicht verfügbar auf: HyperEVM. |
| 200 | -32603 | — | `<node message>` | Nein | Ja | Nach kurzer Verzögerung wiederholen | Anfrage wiederholen; bei anhaltenden Fehlern mit Zeitstempel an den Support wenden. |
| 200 | -32600 | — | `<node message>` | Nein | Nein | — | Einzelne Anfragen im Batch auf nicht konforme Parameter prüfen; aufteilen und wiederholen. |
| 200 | * | — | `<node message>` | Ja | Nein | — | Node hat Berechnung durchgeführt und Aufruf wurde abgerechnet. Revert-Grund/-Daten oder Aufrufparameter prüfen; nicht blindlings wiederholen. |
| 408 | 408 | — | `Zeitüberschreitung der Anfrage nach 35 s zwischen vollständigem Empfang des Anfrage-Headers und der Antwort` | Möglich | Ja | Einige Sekunden warten, bevor Leseaufrufe wiederholt werden | Aufrufe haben möglicherweise die Node erreicht und wurden abgerechnet. Für Leseaufrufe mit Backoff wiederholen. Für Schreibaufrufe (z. B. eth_sendRawTransaction) zuerst den Transaktionsstatus per Hash prüfen. |

### WebSocket-Close-Codes

WebSocket-Verbindungsschließungscodes und empfohlene Client-Aktionen.

| Code | Reason | Bedeutung | Wiederholbar | Wartezeit (Retry-After) | Agent-Aktion |
| --- | --- | --- | --- | --- | --- |
| 1001 | — | `Inaktive Verbindung (Idle)` | Ja | Bei Bedarf neu verbinden | Bei Bedarf neu verbinden. |
| 1003 | — | `Binärframes werden nicht akzeptiert` | Nein | — | Nicht automatisch neu verbinden; nur UTF-8-Textframes senden. |
| 1009 | — | `Nachricht zu groß` | Nein | — | Nicht automatisch neu verbinden; große Anfragen aufteilen, um unter 1 MiB zu bleiben. |
| 1012 | — | `Dienstneustart` | Ja | Mit gejittertem Backoff neu verbinden | Mit gejittertem Backoff neu verbinden, Abonnements erneuern und verpasste Daten nachträglich abrufen. |
| 1013 | — | `Chain nicht verfügbar; überlastet` | Ja | Mit exponentiellem Full-Jitter-Backoff neu verbinden | Mit exponentiellem Full-Jitter-Backoff neu verbinden, Abonnements erneuern und verpasste Daten nachträglich abrufen. |
| 4402 | — | `Unzureichendes Guthaben` | Nein | — | Nicht automatisch neu verbinden; On-Chain aufladen: Einzahlungsadresse in der Konsole oder über `GET /v1/topup/deposit-address` abrufen (MCP `get_deposit_address`); siehe [Leitfaden zur Aufladung für Agenten](https://docs.blockvectra.com/en/guides/agent-topup/) oder Kontingent in der Konsole zurücksetzen, falls berechtigt. |
| 4404 | — | `Ungültiger API-Schlüssel` | Nein | — | Nicht automatisch neu verbinden; API-Schlüssel in der Konsole prüfen oder rotieren. |
| 4408 | — | `Dienst schließt Sitzung, wenn Push-Warteschlange 512 KiB (524.288 Bytes) überschreitet, und verwirft ausstehende Benachrichtigungen; Client erhält möglicherweise keinen Close-Frame (Browser meldet 1006); unerwartete Verbindungsabbrüche wie 4408 behandeln.` | Ja | Mit Backoff neu verbinden; Abonnements reduzieren oder schneller lesen | Unerwarteten Verbindungsabbruch ohne Close-Frame (Browser meldet 1006) wie 4408 behandeln: mit Backoff neu verbinden, Abonnements wiederherstellen und verworfene Daten mit eth_getLogs nachholen; Abonnements reduzieren oder schneller lesen. |
| 4429 | — | `Push-Rate überschritten` | Ja | Mit Backoff neu verbinden oder Abonnements reduzieren | Abonnements reduzieren oder mit Backoff neu verbinden. |
| 4503 | — | `Abrechnungsdienst nicht verfügbar` | Ja | Mit exponentiellem Full-Jitter-Backoff neu verbinden | Mit exponentiellem Full-Jitter-Backoff neu verbinden und erneut abonnieren. |

### Data-API-Fehler

Von den Blockchain-Data-API-Endpunkten unter /v1/data/{chain}/ zurückgegebene Fehler.

| HTTP | Code | Reason | Bedeutung | Berechnet | Wiederholbar | Wartezeit (Retry-After) | Agent-Aktion |
| --- | --- | --- | --- | --- | --- | --- | --- |
| 400 | bad_request | — | `Doppelter Abfrageparameter, ungültige Abfragezeichenfolge oder fehlerhafte Anfrage` | Nein | Nein | — | Abfrageparameter prüfen; sicherstellen, dass Parameter wie limit höchstens einmal vorkommen und Abfrageparameter gültig sind. |
| 409 | not_indexed_yet | — | `Angeforderte Blocknummer oder angefordertes Fenster liegt über as_of_block, oder Hash verweist auf einen Block über as_of_block (enthält indexed_through, sofern die Chain indexierte Blöcke aufweist)` | Nein | Ja | Einige Sekunden warten, bis indexed_through den Block erreicht | Pollen, bis der angeforderte Block oder to_block kleiner oder gleich indexed_through ist, oder warten, bis die Chain beginnt, Blöcke zu schreiben. |
| 409 | window_too_large | — | `Blockfenster umfasst mehr als 100.000 Blöcke und Parameter clamp wurde nicht auf true gesetzt` | Nein | Nein | — | Blockbereich (from_block bis to_block) auf <= 100.000 Blöcke eingrenzen oder clamp=true übergeben. |
| 409 | too_many_pools | — | `Token entspricht mehr als 200 Liquiditätspools; stattdessen nach Pool-Dimension abfragen` | Nein | Nein | — | Nach spezifischer Pool-Adresse abfragen, anstatt alle Pools für den Token abzufragen. |
| 409 | span_exceeded | — | `Angeforderter Datumsbereich überschreitet das Maximum von 90 Tagen` | Nein | Nein | — | Datumsbereich zwischen from_time und to_time auf maximal 90 Tage eingrenzen. |
| 422 | no_coverage | — | `Funktion auf dieser Chain nicht unterstützt oder angeforderter Block liegt vor dem Abdeckungsfenster` | Nein | Nein | — | Vor der Abfrage `features` und `coverage.from_block` in GET /v1/data/chains (oder `data_features` im kostenlosen GET /v1/status) prüfen. |
| 503 | unavailable | — | `Datendienst vorübergehend nicht verfügbar` | Nein | Ja | Einige Sekunden warten und mit exponentiellem Backoff wiederholen | Nach kurzer Verzögerung mit exponentiellem Backoff wiederholen. |
| 402 | insufficient_balance | — | `Kostenpflichtiges Guthaben oder Freikontingent aufgebraucht (wenn Guthaben bekannt ist, enthält error.data balance_units und balance_cu)` | Nein | Nein | — | On-Chain aufladen: Einzahlungsadresse in der Konsole oder über `GET /v1/topup/deposit-address` abrufen (MCP `get_deposit_address`); siehe [Leitfaden zur Aufladung für Agenten](https://docs.blockvectra.com/en/guides/agent-topup/) oder auf Auffüllung des Freikontingents warten. |
| 429 | cost_exceeds_burst | — | `Eine einzelne Anfrage kostet mehr als die Burst-Kapazität des Schlüssels` | Nein | Nein | — | Anfrage in kleinere Anfragen aufteilen; ein erneuter Versuch in unveränderter Form wird nie erfolgreich sein. |
| 503 | gateway_overloaded | — | `Data-API-Kapazität ist vorübergehend nicht verfügbar` | Nein | Ja | Retry-After: 1 Sekunde | Gleichzeitige Anfragen über die Schlüssel und Chains dieses Kontos hinweg reduzieren; vor erneuter Anfrage Retry-After abwarten. error.data.reason ist null. |

### Konsole-, Konto- & Faucet-API-Fehler

Von den Verwaltungs-, Schlüsselbereitstellungs-, Authentifizierungs- und Faucet-Endpunkten unter /v1/ zurückgegebene Fehler.

| HTTP | Code | Reason | Bedeutung | Berechnet | Wiederholbar | Wartezeit (Retry-After) | Agent-Aktion |
| --- | --- | --- | --- | --- | --- | --- | --- |
| 409 | topup_disabled | — | `Aufladung pausiert oder derzeit keine verfügbaren Netzwerke für Aufladungen; neue Adressen können nicht zugewiesen werden, bestehende zugewiesene Adressen bleiben dem Konto jedoch zugeordnet` | Nein | Nein | — | Verfügbarkeit von Aufladungen über GET /v1/topup/status prüfen; später wiederholen, wenn Aufladungen aktiviert sind. |
| 503 | deposit_unavailable | — | `Einzahlungsadresse kann vorübergehend nicht zugewiesen werden; Wiederholung gemäß Retry-After-Header` | Nein | Ja | Retry-After-Header (Sekunden) beachten und exponentielles Backoff verwenden | Gemäß Retry-After-Header mit exponentiellem Backoff wiederholen. |
| 400 | invalid_request | `invalid_username` | `Benutzername-Format ist ungültig (muss alphanumerisch sein oder Unterstriche enthalten)` | Nein | Nein | — | Gültigen Benutzernamen angeben, der den Zeichen- und Längenanforderungen entspricht. |
| 400 | invalid_request | `expires_at` | `Ablaufzeit des Schlüssels liegt nicht in der Zukunft oder überschreitet die maximal zulässige Gültigkeitsdauer` | Nein | Nein | — | expires_at auf einen zukünftigen RFC 3339-Zeitstempel innerhalb des zulässigen Gültigkeitszeitraums festlegen (Standard: 365 Tage), oder expires_in_secs verwenden. |
| 400 | invalid_request | `cu_cap` | `Der Parameter cu_cap liegt außerhalb des gültigen Bereichs (muss eine Ganzzahl zwischen 1 und 9007199254740991 sein)` | Nein | Nein | — | cu_cap auf eine Ganzzahl zwischen 1 und 9007199254740991 anpassen oder weglassen für unbegrenzte CU. |
| 400 | siwe_invalid | `expired` | `Sign-In with Ethereum (SIWE)-Nachricht ist abgelaufen oder Nonce wurde bereits verwendet` | Nein | Ja | Sofort eine neue Challenge abrufen und signieren | Neue Challenge von /v1/auth/siwe/challenge anfordern und die neu ausgestellte Nachricht signieren. |
| 400 | siwe_invalid | `chain_mismatch` | `chainId in der SIWE-Nachricht stimmt nicht mit den Servereinstellungen überein` | Nein | Nein | — | Die von /v1/auth/siwe/challenge zurückgegebene chainId beim Erstellen der SIWE-Nachricht verwenden. |
| 400 | siwe_invalid | `domain_mismatch` | `Domain in der SIWE-Nachricht stimmt nicht mit dem Server-Host überein` | Nein | Nein | — | Sicherstellen, dass Domain und URI mit dem in der Challenge zurückgegebenen Server-Host übereinstimmen. |
| 400 | siwe_invalid | `signature` | `Kryptografische SIWE-Signaturprüfung fehlgeschlagen` | Nein | Nein | — | Überprüfen, ob die Nachricht mit dem privaten Schlüssel der angegebenen Adresse signiert wurde. |
| 409 | key_limit_reached | `active_keys` | `Aktive (nicht widerrufene) API-Schlüssel haben das Kontolimit erreicht` | Nein | Nein | — | Einen vorhandenen ungenutzten Schlüssel widerrufen, bevor ein neuer Schlüssel erstellt wird. |
| 409 | no_reset_available | `nothing_to_reset` | `Guthaben liegt bereits beim oder über dem Rücksetzziel; Rücksetzmöglichkeit bleibt erhalten` | Nein | Nein | — | Derzeit kein Zurücksetzen erforderlich; nutzen Sie die Rücksetzmöglichkeit, nachdem das Guthaben aufgebraucht ist. |
| 429 | rate_limited | `daily_creations` | `24-Stunden-Limit für die Schlüsselerstellung des Kontos erreicht` | Nein | Ja | Retry-After-Header (Sekunden) beachten | Vorhandene Schlüssel rotieren, anstatt neue zu erstellen, oder das Zurücksetzen des 24-Stunden-Fensters abwarten. |
| 429 | signup_rate_limited | `per_ip` | `Registrierungs-Ratenlimit für das Client-IP-Subnetz erreicht` | Nein | Ja | Retry-After-Header (Sekunden) beachten | Das Retry-After-Intervall abwarten, bevor ein neues Konto aus diesem Netzwerk erstellt wird. |
| 429 | signup_rate_limited | `global` | `Globales Ratenlimit für Neuregistrierungen über alle Quellen hinweg erreicht` | Nein | Ja | Retry-After-Header (Sekunden) beachten | Das Retry-After-Intervall abwarten, bevor die Kontoerstellung erneut versucht wird. |
| 400 | oauth_invalid | — | `OAuth-Parameter ungültig oder Callback-Status unbekannt, abgelaufen oder bereits verwendet` | Nein | Ja | — | Einen neuen OAuth-Login-Flow über /v1/auth/{provider}/start initiieren. |
| 400 | login_code_invalid | — | `Login-Code unbekannt, abgelaufen, bereits verwendet oder PKCE-Verifier stimmt nicht überein` | Nein | Nein | — | Login neu starten, um einen neuen Login-Code zu erhalten. |
| 401 | unauthenticated | — | `Sitzung fehlt oder Sitzungstoken ist ungültig, abgelaufen oder widerrufen; bei der Top-up API (/v1/topup/*) tritt dies auch auf, wenn der Authorization-Header einen Nicht-Bearer- oder ungültigen Token anstelle von x-api-key enthält` | Nein | Nein | — | Erneut anmelden, um ein neues Bearer-Sitzungstoken zu erhalten; bei der Top-up API den API-Schlüssel im x-api-key-Header anstelle des Authorization-Headers übergeben. |
| 403 | user_disabled | — | `Konto wurde durch die Administration gesperrt` | Nein | Nein | — | Wenden Sie sich für Kontounterstützung an contact@blockvectra.com. |
| 404 | provider_disabled | — | `OAuth-Anbieter wird erkannt, ist aber derzeit deaktiviert` | Nein | Nein | — | SIWE oder einen anderen unterstützten Authentifizierungsanbieter verwenden. |
| 409 | identity_in_use | — | `Identität (Wallet oder OAuth-Konto) ist bereits mit einem anderen Benutzer verknüpft` | Nein | Nein | — | Die Identität vom vorherigen Konto trennen oder eine andere Identität verwenden. |
| 409 | identity_limit_reached | — | `Maximale Anzahl verknüpfter Identitäten (5) für dieses Konto erreicht` | Nein | Nein | — | Eine nicht benötigte Identität trennen, bevor eine neue verknüpft wird. |
| 409 | last_identity | — | `Die einzige verbleibende Identität kann nicht vom Konto getrennt werden` | Nein | Nein | — | Zuerst eine andere Identität verknüpfen, bevor diese entfernt wird. |
| 409 | key_not_active | — | `Es wurde versucht, einen deaktivierten, widerrufenen oder abgelaufenen API-Schlüssel zu rotieren` | Nein | Nein | — | Einen neuen Schlüssel erstellen oder einen aktiven Schlüssel rotieren. |
| 409 | no_reset_available | — | `Keine Kontingent-Rücksetzmöglichkeiten mehr für dieses Konto vorhanden` | Nein | Nein | — | On-Chain aufladen: Einzahlungsadresse in der Konsole oder über `GET /v1/topup/deposit-address` abrufen (MCP `get_deposit_address`); siehe [Leitfaden zur Aufladung für Agenten](https://docs.blockvectra.com/en/guides/agent-topup/) oder auf den nächsten Aktionszyklus warten. |
| 413 | payload_too_large | — | `Anfragetext überschreitet das Größenlimit von 64 KiB` | Nein | Nein | — | Größe des Anfragetexts auf unter 64 KiB reduzieren. |
| 503 | signup_paused | — | `Globale Neuregistrierungen sind vorübergehend pausiert; bestehende Logins sind nicht betroffen` | Nein | Ja | Registrierung später wiederholen | Neuregistrierungen vorübergehend pausiert; Status prüfen und später erneut versuchen. |
| 503 | usage_unavailable | — | `Nutzungsberichts-Dienst ist vorübergehend nicht verfügbar` | Nein | Ja | Einige Sekunden warten und wiederholen | Betrifft nur den Endpunkt /usage; andere Endpunkte funktionieren normal. In Kürze wiederholen. |
| 500 | internal | — | `Unerwarteter Serverfehler` | Nein | Ja | Nach kurzer Verzögerung wiederholen | Anfrage mit exponentiellem Backoff wiederholen. |
| 400 | invalid_address | `invalid_address` | `Format oder Prüfsumme der Empfängeradresse ist ungültig` | Nein | Nein | — | 0x gefolgt von 40 Hexadezimalzeichen verwenden, kleingeschrieben oder mit EIP-55-Prüfsumme; data.field (/address) prüfen. |
| 503 | faucet_empty | `faucet_empty` | `Das Faucet verfügt über unzureichende Mittel für die Anforderung und die Transaktionsgebühr` | Nein | Ja | Retry-After-Header (Sekunden) beachten | Vor erneutem Versuch Retry-After abwarten; ohne akzeptierte Antwort nicht davon ausgehen, dass Test-ETH gesendet wurden. |
| 503 | service_unavailable | `service_unavailable` | `Faucet-Anforderungsverarbeitung ist vorübergehend nicht verfügbar oder eine vorherige Anforderung hat noch keinen Beleg` | Nein | Ja | Retry-After-Header (Sekunden) beachten | Vor erneutem Versuch Retry-After abwarten; ohne akzeptierte Antwort nicht davon ausgehen, dass Test-ETH gesendet wurden. |

### Push-API-Fehler

Fehler aus der Webhook-Abonnementverwaltung und dem Ereignisverlauf unter /v1/push/.

| HTTP | Code | Reason | Bedeutung | Berechnet | Wiederholbar | Wartezeit (Retry-After) | Agent-Aktion |
| --- | --- | --- | --- | --- | --- | --- | --- |
| 400 | invalid_request | — | `Ungültige Anfragefelder, Adressen, Paginierung oder Blockbereich.` | Nein | Nein | — | data.field und data.invalid prüfen; Anfrage korrigieren. |
| 401 | missing_api_key | — | `x-api-key fehlt.` | Nein | Nein | — | API-Schlüssel im x-api-key-Header bereitstellen. |
| 401 | invalid_api_key | — | `Unbekannter, deaktivierter oder widerrufener API-Schlüssel.` | Nein | Nein | — | Einen aktiven Schlüssel Ihres Kontos verwenden. |
| 402 | insufficient_balance | — | `Guthaben oder Freikontingent für den Ereignisverlauf aufgebraucht.` | Nein | Nein | — | data.reason (balance_exhausted oder free_grant_exhausted) sowie data.balance_units / data.balance_cu (sofern vorhanden) prüfen; über data.topup_url oder data.deposit_address_url aufladen. |
| 403 | key_cap_exhausted | — | `CU-Limit des API-Schlüssels für den Ereignisverlauf aufgebraucht.` | Nein | Nein | — | data.cu_cap prüfen und neuen Schlüssel in der Konsole erstellen. |
| 403 | key_expired | — | `API-Schlüssel ist abgelaufen.` | Nein | Nein | — | Einen nicht abgelaufenen Schlüssel Ihres Kontos verwenden. |
| 404 | not_found | — | `Route, Methode oder Abonnement nicht gefunden.` | Nein | Nein | — | Pfad, Methode und Abonnementzugehörigkeit prüfen. |
| 409 | limit_reached | — | `Limit für Kontoabonnements oder Adresspaare erreicht.` | Nein | Nein | — | data.limit und data.max prüfen; Abonnements oder Adressen reduzieren. |
| 413 | request_too_large | — | `Anfragetext überschreitet das Limit der Route.` | Nein | Nein | — | Adress-Batch aufteilen oder Textgröße verringern. |
| 422 | chain_not_available | — | `Chain für Push nicht verfügbar oder nicht im Abonnement enthalten.` | Nein | Nein | — | GET /v1/push/chains und die Chains des Abonnements prüfen. |
| 422 | chains_required | — | `Mindestens eine Chain ist erforderlich.` | Nein | Nein | — | Ein nicht-leeres chains-Objekt angeben; offline-Status verwenden, um das Belauschen zu stoppen. |
| 422 | confirmations_out_of_range | — | `Bestätigungstiefe liegt außerhalb des Chain-Bereichs.` | Nein | Nein | — | confirmations zwischen data.min und data.max wählen. |
| 422 | destination_not_allowed | — | `Empfänger-URL ist nicht zulässig.` | Nein | Nein | — | data.rule prüfen; HTTPS-Hostnamen auf Port 443 ohne Benutzerinformationen oder Fragment verwenden. |
| 422 | block_out_of_range | — | `Blockbereich liegt außerhalb des verfügbaren Replay- oder Verlaufsbereichs.` | Nein | Nein | — | data.min_block und data.max_block verwenden, um den Bereich anzupassen. |
| 429 | cost_exceeds_burst | — | `Kosten der Verlaufsanfrage übersteigen die Burst-Kapazität des Schlüssels.` | Nein | Nein | — | data.reason (request_exceeds_burst) und data.max prüfen; Burst-Kapazität vor Wiederholung erhöhen. Unverändertes Wiederholen hilft nicht. |
| 429 | rate_limited | — | `Ratenlimit für Verwaltung oder Verlaufsabfragen erreicht.` | Nein | Ja | Sekunden im Retry-After abwarten. | Für Verlauf data.reason (key_rate_limit oder free_plan_call_limit) prüfen; Retry-After-Sekunden abwarten und Anfragefrequenz oder Parallelität verringern. |
| 500 | internal_error | — | `Unerwarteter Dienstfehler.` | Nein | Nein | — | x-request-id notieren und Support kontaktieren. |
| 503 | auth_unavailable | — | `API-Schlüssel-Validierung vorübergehend nicht verfügbar.` | Nein | Ja | Vor Wiederholung Retry-After-Sekunden abwarten. | Vor Wiederholung Retry-After-Sekunden abwarten. |
| 503 | billing_unavailable | — | `Abrechnungsstatus für Verlauf vorübergehend nicht verfügbar.` | Nein | Ja | Vor Wiederholung Retry-After-Sekunden abwarten. | Vor Wiederholung Retry-After-Sekunden abwarten. |
| 503 | upstream_unavailable | — | `Push-Dienst vorübergehend nicht erreichbar.` | Nein | Ja | Vor Wiederholung Retry-After-Sekunden abwarten. | Vor Wiederholung Retry-After-Sekunden abwarten. |
| 503 | service_unavailable | — | `Push-Dienst oder Adresskapazität vorübergehend nicht verfügbar.` | Nein | Ja | Vor Wiederholung Retry-After-Sekunden abwarten. | Vor Wiederholung Retry-After-Sekunden abwarten. |

Befolgen Sie bei Fehlern bei Webhook-Abonnements oder der erneuten Zustellung (Replay) den [Leitfaden zur Wiederherstellung von Push-Zustellungen](https://docs.blockvectra.com/de/guides/webhook-push/#delivery-retries-and-replay). Die Empfängerintegration beginnt mit der [Signaturüberprüfung anhand des Raw-Bodys](https://docs.blockvectra.com/de/guides/webhook-push/#verify-signatures); das [Stablecoin-Zahlungsbeispiel](https://docs.blockvectra.com/de/guides/stablecoin-payments/#receive-payments-with-webhooks) ergänzt Ereignis-Deduplizierung, Receipt-Prüfungen, Lücken-Backfill und Reorg-Bereinigung. Siehe [Abrechnungsregeln](https://docs.blockvectra.com/de/guides/billing-rules/#webhook-push-billing) zur Verbrauchsmessung und [WebSocket-Wiederverbindung](https://docs.blockvectra.com/de/guides/websocket-subscriptions/#reconnection-and-exponential-backoff) für verbindungsbasierte Abonnements.

Prüfen Sie bei `logs_range_too_large` die [eth\_getLogs-Methodenparameter](https://docs.blockvectra.com/de/api/json-rpc/methods/eth_getLogs/) und folgen Sie dem [Leitfaden für Blockbereichslimits und partitionierte Abfragen](https://docs.blockvectra.com/de/guides/getlogs-block-range/).

Für Faucet-Anforderungen auf Robinhood Chain siehe den [Testnet-Faucet-Leitfaden](https://docs.blockvectra.com/de/guides/robinhood-testnet-faucet/) zu Voraussetzungen und zum Umgang mit gemeinsamen Fehlercodes.