Reference

Error codes

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

Open as Markdown

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" }]
}
FieldMeaning
errorFixed identifier. Your code should check this.
messageReadable sentence in English, in German with the header Accept-Language: de. The wording may change.
detailsOnly for invalid_body: for each entry the field (path) and the reason (always in English).

All identifiers

StatuserrorMeaningWhat to do
400invalid_bodyA field is missing, too long or has the wrong type.Read details and fix the body. Don't repeat it unchanged.
401missing_keyThe Authorization header is missing or doesn't start with Bearer.Set the header Authorization: Bearer <PACKLETS_KEY>.
401invalid_keyThe 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.
401invalid_tokensession-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().
409wrong_kindPUT /v1/ui on a channel. Only an app has a page.Connect again and choose Your own app. The type can't be changed.
429rate_limitedMore 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:

StatuscodeMeaning
400FST_ERR_CTP_INVALID_JSON_BODYThe body isn't valid JSON. Often a missing quotation mark or an extra comma.
400FST_ERR_CTP_EMPTY_JSON_BODYContent-Type: application/json, but no body.
413FST_ERR_CTP_BODY_TOO_LARGEThe body is larger than 64 KiB.
415FST_ERR_CTP_INVALID_MEDIA_TYPEThe Content-Type is neither JSON nor a form.

Retry or not

ResponseRetry?
429, 5xx, no connection, timeoutYes, after a pause.
400, 401, 409, 413, 415No. Fix the cause first.

If nothing arrives despite 200, Troubleshooting helps.