# Fehler

> Das eine Fehlerformat, wie du es liest und wie du entscheidest, ob du es noch einmal versuchst. Die ganze Liste der Codes mit Ursache und Lösung steht im Fehlerkatalog.

Stand: 2026-10-30. Quelle: https://docs.smartchat.marketing/de/concepts/errors-overview/

Jeder Fehler der API hat dasselbe Format (RFC 9457, Content-Type `application/problem+json`). Das gilt für alle Fehler: falscher Schlüssel, unbekannter Pfad, falsche Eingabe, zu viele Anfragen und Probleme auf unserer Seite.

```json
{
  "type": "https://docs.smartchat.marketing/en/errors#insufficient_scope",
  "title": "Missing permission",
  "status": 403,
  "error_type": "permission",
  "code": "insufficient_scope",
  "message": "This key lacks the permission 'contacts:write'.",
  "param": null,
  "retryable": false,
  "doc_url": "https://docs.smartchat.marketing/en/errors#insufficient_scope",
  "request_id": "req_01JAB9C3X7K2M4N5P6Q7R8S9T0",
  "required_scope": "contacts:write"
}
```

## Felder

| Name | Type | Required | Description |
|---|---|---|---|
| `type` | string | yes | URL of the documentation for this error. up to 300 characters |
| `title` | string | yes | Short title. up to 100 characters |
| `status` | integer | yes | HTTP status. 400 to 599 |
| `error_type` | string | yes | Stable error class. Branch on this first, then on code. one of: `authentication`, `permission`, `invalid_request`, `conflict`, `rate_limit`, `api` |
| `instance` | string | no | Path of the request that failed. up to 300 characters |
| `code` | string | yes | Stable error code from the error catalog. up to 60 characters |
| `message` | string | yes | English explanation. Contains no personal data. up to 500 characters |
| `param` | string or null | no | Path of the invalid field, for example body.tags[2]. up to 200 characters |
| `retryable` | boolean | yes | True if the same request may work later. |
| `doc_url` | string | yes | Link to the error page. up to 300 characters |
| `request_id` | string | yes | ID of the request, also in the Request-Id header. up to 40 characters |
| `errors` | array of object | no | All input errors when more than one field is invalid. up to 50 items |
| `errors[].param` | string | yes | Path of the field. up to 200 characters |
| `errors[].code` | string | yes | Error code. up to 60 characters |
| `errors[].message` | string | yes | English explanation. up to 500 characters |

Manche Fehler fügen Felder hinzu, die zu ihnen gehören, zum Beispiel `required_scope`, `existing_id` oder `limit`. Ihre Bedeutung steht beim Code im [Fehlerkatalog](https://docs.smartchat.marketing/de/errors/).

## So gehst du mit einem Fehler um

1. Sieh zuerst auf `error_type`. Er ist einer von `authentication`, `permission`, `invalid_request`, `conflict`, `rate_limit` oder `api`. Er ändert sich für einen Code nie.
2. Dann sieh auf `code`. Codes sind stabil. Die `message` ist für Menschen; werte sie nicht automatisch aus.
3. Ist `retryable` gleich `true`, kann dieselbe Anfrage später klappen. Bei `rate_limited` warte die Sekunden aus `Retry-After`. Sonst ändere die Anfrage.
4. Behalte die `request_id`. Wenn du Hilfe brauchst, [schreibe dem Support](https://docs.smartchat.marketing/de/support/) und nenne sie.

## 400 und 422

- **400**: Die Anfrage ist nicht richtig gebaut. Zum Beispiel ist der Body kein JSON, ein Feld fehlt oder ist unbekannt, oder der Cursor ist kaputt.
- **422**: Die Anfrage ist richtig gebaut, aber ihr Inhalt verletzt eine Regel. Zum Beispiel ist eine Telefonnummer ungültig oder der Kontakt hat kein Opt-in.

## Mehrere falsche Felder

Sind mehrere Felder falsch, listet `errors` alle in einer Antwort auf, jedes mit `param`, `code` und `message`. Der `param` ist der Pfad des Felds, zum Beispiel `body.tags[2]`.

## Nie ein Fehler, den du nicht verfolgen kannst

Fehlermeldungen enthalten keine persönlichen Daten. Meldet ein verbundener Dienst wie WhatsApp ein Problem, bekommst du [`upstream_error`](https://docs.smartchat.marketing/de/errors/#upstream_error) mit einem kurzen Code, nie den Rohtext des anderen Dienstes.