> For the complete documentation index, see [llms.txt](https://docs.metasleuth.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.metasleuth.io/de/blocksec-aml-api/introduction/response-format.md).

# Antwortformat

Eine Geschäfts-API-Anfrage ist nur erfolgreich, wenn der HTTP-Status **200** und der oberste JSON-`code` **200000** ist. Prüfen Sie beide Werte; HTTP 200 allein zeigt keinen Erfolg an.

## Antwortfelder

| Feld         | Beschreibung                                                                                                               |
| ------------ | -------------------------------------------------------------------------------------------------------------------------- |
| `request_id` | Anfragekennung, falls verfügbar. Geben Sie sie bei Support-Anfragen an. Sie kann leer sein.                                |
| `code`       | Ganzzahliger Geschäftsstatuscode. `200000` bedeutet Erfolg. Er ist unabhängig von Adressetikett- und Risikoindikatorcodes. |
| `message`    | Ergebnisbeschreibung. Behandeln Sie Fehler anhand des Geschäftscodes statt durch Textvergleich.                            |
| `data`       | Endpunktspezifische Ergebnisdaten. Dieses Feld kann in Fehlerantworten fehlen.                                             |
| `cause`      | Optionale zusätzliche Fehlerdetails einer Address Label API-Antwort.                                                       |

Eine ungültige Signatur liefert beispielsweise HTTP 401:

```json
{
  "request_id": "example-request-id",
  "code": 401002,
  "message": "Invalid request signature"
}
```

Nicht jeder Fehler liefert JSON oder einen Geschäftscode. Behandeln Sie auch leere und nicht als JSON vorliegende Fehlerantworten.

## Authentifizierungs- und Sicherheitsfehler

Die folgenden Codes gelten für registrierte Geschäftsendpunkte der Address Label API und Risk Score API.

| Code     | HTTP | Meldung                                                                 | Empfohlene Maßnahme                                                                                                                                                                                                                  |
| -------- | ---- | ----------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `403001` | 403  | API security setup is required. Enable IP allowlist or request signing. | Öffnen Sie API Security Settings und schließen Sie die erforderliche Einrichtung der API-Verwaltungsseite ab.                                                                                                                        |
| `403002` | 403  | Request IP is not allowed                                               | Prüfen Sie die öffentliche Ausgangs-IP Ihrer Anwendung und die konfigurierte IP Allowlist.                                                                                                                                           |
| `401001` | 401  | Request signing is not configured                                       | Konfigurieren Sie Request Signing und stellen Sie sicher, dass ein Secret für diesen Dienst verfügbar ist.                                                                                                                           |
| `401002` | 401  | Invalid request signature                                               | Prüfen Sie alle Signatur-Header, Secret, Methode, vollständigen Pfad, normalisierte Abfrage und exakte Body-Bytes. Unvollständige Header, ungültige Signaturlänge oder eine Nonce über 256 Byte verursachen diesen Fehler ebenfalls. |
| `401003` | 401  | Invalid request timestamp                                               | Verwenden Sie Unix-Zeitstempel in Sekunden. Synchronisieren Sie Ihre Uhr; die Abweichung zur Serverzeit darf höchstens 5 Minuten betragen.                                                                                           |
| `401004` | 401  | Request has already been used                                           | Erstellen Sie vor dem Wiederholen eine neue Nonce und berechnen Sie die Signatur neu.                                                                                                                                                |
| `413001` | 413  | Request body is too large                                               | Begrenzen Sie den Body auf 16 MiB und prüfen Sie auf unterbrochene oder unvollständige Uploads.                                                                                                                                      |

Sind IP Allowlist und Request Signing aktiv, müssen beide Prüfungen bestanden werden. Jeder nicht leere Signatur-Header löst die Prüfung auch bei deaktiviertem Request Signing aus. Die Antwort nennt die erste fehlgeschlagene Sicherheitsprüfung.

Aus Sicherheitsgründen abgelehnte Anfragen werden nicht an die Geschäftsverarbeitung weitergeleitet und nicht berechnet.

## Dienstfehler

| Code     | HTTP | Meldung                                     | Empfohlene Maßnahme                                                                                                                                |
| -------- | ---- | ------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| `500001` | 500  | API security policy is unavailable          | Wiederholen Sie mit begrenztem exponentiellem Backoff. Kontaktieren Sie bei fortbestehenden Problemen den Support.                                 |
| `500002` | 500  | API subscription information is unavailable | Wiederholen Sie mit begrenztem exponentiellem Backoff. Kontaktieren Sie bei fortbestehenden Problemen den Support.                                 |
| `500003` | 500  | Request signing verification is unavailable | Wiederholen Sie mit begrenztem exponentiellem Backoff, neuer Nonce und neuer Signatur. Kontaktieren Sie bei fortbestehenden Problemen den Support. |
| `502001` | 502  | Invalid upstream response                   | Kontaktieren Sie den Support mit Anfragedetails und Anfrage-ID, falls vorhanden.                                                                   |
| `502002` | 502  | Failed to receive upstream response         | Wiederholen Sie mit begrenztem exponentiellem Backoff. Kontaktieren Sie bei fortbestehenden Problemen den Support.                                 |

## Bestehende Geschäftscodes

Bestehende Codes werden weiterhin unterstützt. Meldungen können je nach Dienst oder Version abweichen; identifizieren Sie den Fehler über `code`.

| Code     | Beschreibung                                                                         | Empfohlene Maßnahme                                                                                                                              |
| -------- | ------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `200000` | Success                                                                              | Lesen Sie die endpunktspezifischen `data`.                                                                                                       |
| `400001` | Unauthorized operation                                                               | Prüfen Sie Ihre Zugriffsrechte. Dieser Code ist unabhängig von den obigen Sicherheitscodes.                                                      |
| `400002` | Request rate is too high. Please try again later.                                    | Senken Sie die Anfragefrequenz und verwenden Sie Backoff. Antworten bei Ratenbegrenzung verwenden HTTP 429.                                      |
| `400004` | Invalid params                                                                       | Prüfen Sie das Anfrageschema des Endpunkts.                                                                                                      |
| `400005` | User does not exist                                                                  | Aus Kompatibilitätsgründen beibehaltener Altcode.                                                                                                |
| `400006` | Server busy                                                                          | Wiederholen Sie mit begrenztem exponentiellem Backoff.                                                                                           |
| `400007` | Invalid API key                                                                      | Prüfen Sie Schlüssel, Dienst und Gültigkeit. Die Meldung kann `Invalid api-key` lauten.                                                          |
| `400008` | Invalid auth format                                                                  | Aus Kompatibilitätsgründen beibehaltener Altcode; prüfen Sie die Authentifizierungs-Header.                                                      |
| `400009` | The API key is expired                                                               | Prüfen Sie Ihren API-Zugriff und beschaffen Sie gültige Zugangsdaten.                                                                            |
| `400010` | Route not found                                                                      | Prüfen Sie Basis-URL und Endpunktpfad. Die Meldung kann `Router not found!` oder `404 not found!` lauten.                                        |
| `400011` | Invalid address. Please ensure that you have provided the correct chain and address. | Prüfen Sie die Adresse und ihre Chain.                                                                                                           |
| `400012` | Daily request limit exceeded. Please try again tomorrow.                             | Prüfen Sie das verbleibende Kontingent und die nächste Rücksetzung. Kontingentbegrenzungen verwenden HTTP 429.                                   |
| `400013` | Unsupported chain                                                                    | Prüfen Sie `chain_id`. Aktuell lautet die Meldung `Invalid params. Unsupported chain id`; ältere Dokumentation nennt den Chain-Namen.            |
| `400014` | Method not allowed                                                                   | Prüfen Sie die HTTP-Methode. Möglich ist auch HTTP 405 ohne Geschäftscode.                                                                       |
| `400015` | The number of addresses in a single request exceeds the limit.                       | Reduzieren Sie die Stapelgröße. Bei chainübergreifenden Etikettabfragen zählt die Anzahl der Eingabeadressen multipliziert mit der Chain-Anzahl. |
| `500000` | Internal error                                                                       | Wiederholen Sie mit begrenztem exponentiellem Backoff. Kontaktieren Sie bei fortbestehenden Problemen den Support.                               |

## Ratenbegrenzung und Kontingent

Begrenzungsantworten verwenden HTTP **429**, mit `400002` für Anfragefrequenz oder `400012` für fehlendes Tageskontingent. Reicht das Kontingent nicht für den gesamten Stapel, werden keine Geschäftsdaten zurückgegeben und keine Teilkosten berechnet.

Falls vorhanden, beschreiben folgende Header das Tageskontingent:

| Header                  | Bedeutung                                                                          |
| ----------------------- | ---------------------------------------------------------------------------------- |
| `X-RateLimit-Limit`     | Tageskontingentgrenze.                                                             |
| `X-RateLimit-Used`      | Verbrauchtes Kontingent.                                                           |
| `X-RateLimit-Remaining` | Verbleibendes Kontingent.                                                          |
| `X-RateLimit-Reset`     | Nächste Rücksetzung: die nächste UTC-Mitternacht als Unix-Zeitstempel in Sekunden. |
| `X-RateLimit-Cost`      | Für diese Antwort berechnetes Kontingent.                                          |

Authentifizierungsablehnungen enthalten keine Kontingent-Header. Der Dienst liefert derzeit kein `Retry-After`. Listen unterstützter Chains und Risikoindikatoren erfordern auch ohne Kontingentkosten Authentifizierung, relevante Sicherheitsprüfungen und Einhaltung der Ratenbegrenzung.

## Sicher wiederholen

* Erstellen Sie für jeden signierten Wiederholungsversuch einen neuen Zeitstempel, eine neue Nonce und Signatur.
* Eine Nonce verhindert Replay; sie ist kein Idempotenzschlüssel. Erfolgreiche Wiederholungen können erneut berechnet werden.
* Wiederholen Sie Anfragen mit ungültigen Zugangsdaten, Signaturen, unzulässigen IPs oder Parametern erst nach Beheben der Ursache.
* Verwenden Sie bei vorübergehenden Dienstfehlern begrenzten exponentiellen Backoff. Bei verlorener Antwort oder unklarem Ergebnis dürfen Sie nicht davon ausgehen, dass die ursprüngliche Anfrage weder verarbeitet noch berechnet wurde.

## Fehler ohne Geschäftscode

Manche Fehler enthalten nur einen HTTP-Status und einen leeren oder nicht als JSON vorliegenden Body.

| HTTP | Mögliche Ursache                                                   | Empfohlene Maßnahme                                                                          |
| ---- | ------------------------------------------------------------------ | -------------------------------------------------------------------------------------------- |
| 404  | Unbekannter Endpunkt.                                              | Prüfen Sie Basis-URL und Pfad.                                                               |
| 405  | Nicht unterstützte Methode.                                        | Prüfen Sie Endpunktmethode und gegebenenfalls den Header `Allow`.                            |
| 413  | Anfrage vor der Signaturprüfung aufgrund der Body-Größe abgelehnt. | Reduzieren Sie die Body-Größe.                                                               |
| 500  | Unerwarteter Serverfehler.                                         | Begrenzen Sie Wiederholungen und kontaktieren Sie bei fortbestehenden Problemen den Support. |
| 502  | Kommunikationsfehler mit dem zugrunde liegenden API-Dienst.        | Begrenzen Sie Wiederholungen und kontaktieren Sie bei fortbestehenden Problemen den Support. |
| 503  | Timeout oder vorübergehende Dienststörung.                         | Wiederholen Sie mit begrenztem exponentiellem Backoff.                                       |

Geben Sie beim Kontakt mit dem [Support](mailto:ms_support@blocksec.com) Endpunkt, HTTP-Methode, UTC-Anfragezeit, HTTP-Status, Geschäftscode und Anfrage-ID an, falls vorhanden. Senden Sie keine API-Schlüssel, Secrets, Signaturen oder Autorisierungs-Header. Teilen Sie nur den Endpunktpfad ohne sensible Abfragewerte und schwärzen Sie Zugangsdaten, personenbezogene Daten und sensible Anfrage-/Antwortdaten in Protokollen, Screenshots und Anhängen.
