Reference
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 helps.