> For the complete documentation index see https://domscan.net/llms.txt. Markdown versions of every docs page are available by appending .md to the page URL.

Source: https://domscan.net/de/docs/error-codes

# Fehlercodes

Entdecken Sie die API-Dokumentation zu Fehlercodes, Anfrageparameter, Antwortfelder, Codebeispiele und Fehlerbehandlung für DomScan-Integrationen.

### Strukturierte Fehler

Jeder API-Fehler liefert dieselbe JSON-Struktur: ein Objekt `error` mit stabilem `code`, lesbarer `message`, `type` und HTTP-`status`, dem Hinweis, ob er `retryable` ist, der `request_id` und einer `docs_url`. Die `request_id` entspricht immer dem Antwort-Header `X-Request-Id`; geben Sie sie daher an, wenn Sie den Support kontaktieren.

```json
{
  "error": {
    "code": "INVALID_DOMAIN",
    "message": "Ungültiges Domainformat",
    "suggestion": "Verwenden Sie eine registrierbare Domain wie example.com",
    "type": "validation_error",
    "status": 400,
    "retryable": false,
    "request_id": "m5x7k2p-a9f3",
    "docs_url": "https://domscan.net/docs/check-availability"
  }
}
```

### Fehlerfelder

| Feld | Beschreibung |
| --- | --- |
| `code` | Stabiler, maschinenlesbarer Fehlercode. Codes werden nie umbenannt, daher können Sie sich bei Ihrer Verzweigungslogik bedenkenlos darauf stützen. |
| `message` | Lesbare Erklärung des Fehlers. Der Wortlaut kann sich ändern, werten Sie ihn daher nicht maschinell aus. |
| `type` | Grobe Fehlerkategorie, zum Beispiel `validation_error`, `authentication_error` oder `rate_limit_error`. |
| `status` | Der HTTP-Statuscode, für Logs und Warteschlangen zusätzlich im Body wiederholt. |
| `retryable` | Gibt an, ob dieselbe Anfrage bei einem späteren erneuten Versuch erfolgreich sein kann. |
| `request_id` | Eindeutige Anfragekennung. Entspricht dem Header `X-Request-Id`. |
| `docs_url` | Link zum Abschnitt der Dokumentation, der diesen Fehler erklärt. |
| `suggestion` | Optionaler Hinweis, wie sich die Anfrage korrigieren lässt. |
| `details` | Optionaler strukturierter Kontext, etwa die erlaubten Methoden oder der ungültige Parameter. |
| `retry_after` | Optionale Anzahl an Sekunden, die Sie vor einem erneuten Versuch warten sollten. Wird auch als Header `Retry-After` gesendet. |

### Häufige Fehlercodes

Dies sind die Codes, die die meisten Clients behandeln müssen. Einige Endpunkte liefern spezifischere Codes, die denselben Regeln folgen; die vollständige Liste mit Status, Typ und Wiederholungsverhalten finden Sie in der OpenAPI-Spezifikation unter `x-domscan-error-codes`. `RATE_LIMIT_EXCEEDED` wird weiterhin als Alias von `RATE_LIMITED` akzeptiert.

| Code | HTTP-Status | Typ | Wiederholbar | Beschreibung |
| --- | --- | --- | --- | --- |
| `BAD_REQUEST` | 400 | `validation_error` | Nein | Fehlende oder ungültige Parameter |
| `MISSING_PARAMETER` | 400 | `validation_error` | Nein | Ein erforderlicher Parameter fehlt |
| `INVALID_PARAMETER` | 400 | `validation_error` | Nein | Ein Parameter hat einen ungültigen Wert |
| `INVALID_JSON` | 400 | `validation_error` | Nein | Der Anfrage-Body ist kein gültiges JSON |
| `INVALID_DOMAIN` | 400 | `validation_error` | Nein | Ungültiges Domainformat |
| `UNSUPPORTED_TLD` | 400 | `validation_error` | Nein | TLD nicht unterstützt |
| `SUBDOMAIN_NOT_SUPPORTED` | 400 | `validation_error` | Nein | Dieser Endpunkt akzeptiert registrierbare Domains, keine Subdomains |
| `VALIDATION_ERROR` | 422 | `validation_error` | Nein | Die Anfrage ist korrekt aufgebaut, kann aber nicht verarbeitet werden |
| `AUTH_REQUIRED` | 401 | `authentication_error` | Nein | Es wurde weder ein API-Schlüssel noch eine Sitzung übermittelt |
| `INVALID_API_KEY` | 401 | `authentication_error` | Nein | Der API-Schlüssel ist ungültig oder wurde widerrufen |
| `INSUFFICIENT_CREDITS` | 402 | `credits_error` | Nein | Ihr Konto verfügt nicht über genügend Credits für diese Anfrage |
| `FORBIDDEN` | 403 | `permission_error` | Nein | Sie haben keine Berechtigung für diese Aktion |
| `NOT_FOUND` | 404 | `not_found_error` | Nein | Der Endpunkt oder die Ressource existiert nicht |
| `METHOD_NOT_ALLOWED` | 405 | `request_error` | Nein | Der Endpunkt existiert, akzeptiert aber diese HTTP-Methode nicht. Der Header `Allow` listet die unterstützten Methoden auf. |
| `CONFLICT` | 409 | `conflict_error` | Nein | Die Anfrage steht im Konflikt mit dem aktuellen Zustand der Ressource |
| `IDEMPOTENCY_CONFLICT` | 409 | `conflict_error` | Nein | Der Idempotenzschlüssel wurde bereits für eine andere Anfrage verwendet |
| `IDEMPOTENCY_KEY_REUSED` | 422 | `validation_error` | Nein | Dieser `Idempotency-Key` wurde in den letzten 24 Stunden bereits mit einer anderen Anfrage verwendet. Verwenden Sie für eine neue Anfrage einen neuen Schlüssel. |
| `IDEMPOTENCY_IN_PROGRESS` | 409 | `conflict_error` | Ja | Eine Anfrage mit diesem `Idempotency-Key` läuft noch. Versuchen Sie es in einem Moment erneut, um die gespeicherte Antwort zu erhalten. |
| `RATE_LIMITED` | 429 | `rate_limit_error` | Ja | Zu viele Anfragen |
| `INTERNAL` | 500 | `api_error` | Nein | Unerwarteter Serverfehler. Wenden Sie sich bei anhaltendem Auftreten mit der Anfrage-ID an den Support. |
| `UPSTREAM_ERROR` | 502 | `upstream_error` | Ja | Eine vorgelagerte Quelle hat eine unbrauchbare Antwort geliefert |
| `UPSTREAM_UNAVAILABLE` | 503 | `upstream_error` | Ja | Eine vorgelagerte Quelle ist vorübergehend nicht verfügbar |
| `SERVICE_UNAVAILABLE` | 503 | `upstream_error` | Ja | Der Dienst ist vorübergehend nicht verfügbar |
| `TIMEOUT` | 504 | `timeout_error` | Ja | Eine vorgelagerte Quelle oder Registry hat nicht rechtzeitig geantwortet |

### Hinweise zu Wiederholungen

- Wiederholen Sie die Anfrage nur, wenn `retryable` den Wert `true` hat. Bei Validierungs-, Authentifizierungs- und Berechtigungsfehlern korrigieren Sie zuerst die Anfrage.

- Ist `retry_after` oder der Header `Retry-After` vorhanden, warten Sie mindestens so viele Sekunden bis zum nächsten Versuch.

- Verwenden Sie andernfalls exponentielles Backoff mit Jitter, zum Beispiel 1, 2, 4 und 8 Sekunden, und brechen Sie nach einigen Versuchen ab.

- Senden Sie beim Anlegen von Batches und Jobs einen Header `Idempotency-Key`, damit eine wiederholte Anfrage nie einen doppelten Job erzeugt.

- Bei anderen POST-Anfragen, die Credits berechnen, sorgt ein `Idempotency-Key`-Header dafür, dass ein erneuter Versuch die gespeicherte Antwort zurückgibt, statt erneut zu berechnen.

### Kompatibilität

Seit dem 10. Oktober 2026 verwenden alle Endpunkte dieses Format. Felder, die einige Endpunkte bereits zurückgaben, etwa `credits_remaining`, `purchase_url`, `login_url`, `success` oder `meta`, bleiben während einer Übergangsphase erhalten, sodass bestehende Integrationen weiter funktionieren. Lesen Sie Fehlerdetails in neuem Code aus dem Objekt `error`.