# Fehlercodes

Alle Fehler aller Aufrufe an einer Stelle, mit dem, was du tun kannst.

Alle Fehler von `POST /v1/push`, `PUT /v1/ui` und `POST /v1/session-token/verify`.

## Aufbau eines Fehlers

```json
{
  "error": "invalid_body",
  "message": "Ungültige Daten.",
  "details": [{ "path": "text", "message": "text darf nicht leer sein" }]
}
```

| Feld | Bedeutung |
|---|---|
| `error` | Feste Kennung. Darauf prüft dein Code. |
| `message` | Lesbarer Satz auf Deutsch. Der Wortlaut kann sich ändern. |
| `details` | Nur bei `invalid_body`: je Eintrag das Feld (`path`) und der Grund. |

## Alle Kennungen

| Status | `error` | Bedeutung | Was tun |
|---|---|---|---|
| 400 | `invalid_body` | Ein Feld fehlt, ist zu lang oder hat den falschen Typ. | `details` lesen und den Body korrigieren. Nicht unverändert wiederholen. |
| 401 | `missing_key` | Der Header `Authorization` fehlt oder beginnt nicht mit `Bearer`. | Header `Authorization: Bearer <SAMY_KEY>` setzen. |
| 401 | `invalid_key` | Der Schlüssel ist falsch, wurde neu erzeugt, oder das Packlet wurde entfernt. | Aktuellen Schlüssel eintragen. Ist er verloren, in der App einen neuen erzeugen. |
| 401 | `invalid_token` | Nur `session-token/verify`: Das Token ist abgelaufen, gefälscht oder gehört zu keinem Packlet. | Die Seite holt mit `samy.token()` ein frisches Token. |
| 409 | `wrong_kind` | `PUT /v1/ui` bei einem Kanal. Nur eine App hat eine Seite. | Ein neues Packlet mit **Eigene App bauen** verbinden. Die Art lässt sich nicht ändern. |
| 429 | `rate_limited` | Mehr als 60 Aufrufe in einer Minute. | So lange warten, wie der Header `retry-after` sagt, dann erneut senden. |

## Fehler ohne Kennung von Samy

Ist schon die Anfrage selbst kaputt, antwortet der Server mit einem allgemeinen Fehler. Das Feld `code` sagt, was es war:

| Status | `code` | Bedeutung |
|---|---|---|
| 400 | `FST_ERR_CTP_INVALID_JSON_BODY` | Der Body ist kein gültiges JSON. Oft ein fehlendes Anführungszeichen oder ein Komma zu viel. |
| 400 | `FST_ERR_CTP_EMPTY_JSON_BODY` | `Content-Type: application/json`, aber kein Body. |
| 413 | `FST_ERR_CTP_BODY_TOO_LARGE` | Der Body ist größer als 64 KiB. |
| 415 | `FST_ERR_CTP_INVALID_MEDIA_TYPE` | Der `Content-Type` ist weder JSON noch ein Formular. |

## Wiederholen oder nicht

| Antwort | Wiederholen? |
|---|---|
| `429`, `5xx`, keine Verbindung, Zeitüberschreitung | Ja, nach einer Pause. |
| `400`, `401`, `409`, `413`, `415` | Nein. Erst die Ursache beheben. |

Kommt trotz `200` nichts an, hilft die [Fehlersuche](https://packlets.app/docs/fehlersuche.md).