# Error codes

All errors of all calls in one place, with what you can do about them.

All errors from `POST /v1/push`, `PUT /v1/ui` and `POST /v1/session-token/verify`.

## Structure of an error

```json
{
  "error": "invalid_body",
  "message": "Invalid data.",
  "details": [{ "path": "text", "message": "text must not be empty" }]
}
```

| Field | Meaning |
|---|---|
| `error` | Fixed identifier. Your code should check this. |
| `message` | Readable sentence in English, in German with the header `Accept-Language: de`. The wording may change. |
| `details` | Only for `invalid_body`: for each entry the field (`path`) and the reason (always in English). |

## All identifiers

| Status | `error` | Meaning | What to do |
|---|---|---|---|
| 400 | `invalid_body` | A field is missing, too long or has the wrong type. | Read `details` and fix the body. Don't repeat it unchanged. |
| 401 | `missing_key` | The `Authorization` header is missing or doesn't start with `Bearer`. | Set the header `Authorization: Bearer <PACKLETS_KEY>`. |
| 401 | `invalid_key` | The key is wrong, was regenerated, or the packlet was removed. | Enter the current key. If it's lost, create a new one in the app. |
| 401 | `invalid_token` | `session-token/verify` only: the token has expired, is forged or doesn't belong to any packlet. | The page gets a fresh token with `packlets.token()`. |
| 409 | `wrong_kind` | `PUT /v1/ui` on a channel. Only an app has a page. | Connect again and choose **Your own app**. The type can't be changed. |
| 429 | `rate_limited` | More than 60 calls in a minute for this packlet, or more than 300 for your whole account. | Wait as long as the `retry-after` header says, then send again. |

## Errors without an identifier from Packlets

If the request itself is broken, the server responds with a general error. The `code` field says what it was:

| Status | `code` | Meaning |
|---|---|---|
| 400 | `FST_ERR_CTP_INVALID_JSON_BODY` | The body isn't valid JSON. Often a missing quotation mark or an extra comma. |
| 400 | `FST_ERR_CTP_EMPTY_JSON_BODY` | `Content-Type: application/json`, but no body. |
| 413 | `FST_ERR_CTP_BODY_TOO_LARGE` | The body is larger than 64 KiB. |
| 415 | `FST_ERR_CTP_INVALID_MEDIA_TYPE` | The `Content-Type` is neither JSON nor a form. |

## Retry or not

| Response | Retry? |
|---|---|
| `429`, `5xx`, no connection, timeout | Yes, after a pause. |
| `400`, `401`, `409`, `413`, `415` | No. Fix the cause first. |

If nothing arrives despite `200`, [Troubleshooting](https://packlets.app/en/docs/fehlersuche.md) helps.
