Responses and errors

A success is a JSON object with status: true, a human-readable statusText, and the result in data:

{ "status": true, "statusText": "Pages fetched.", "data": [] }

A few routes put a value beside data instead of inside it (a new task's id, a list's hasMore); each route below shows its own response.

A failure is a JSON object with status: false and the reason in statusText, message or both:

{ "status": false, "statusText": "Page not found." }

Some failures add error, a machine-readable code, the permission key that was missing, or the field that was refused.

Status codes. The web app expects HTTP 200 on a handled failure and reads status from the body. A request made with an API token gets a real status code instead: when a handler answers 200 with status: false, the server changes the status line to the matching 4xx and adds the header X-Status-Mapped: 1. The body is not changed. Any other caller can ask for the same with the header Prefer: status-codes. The code is the handler's own statusCode when it sets one, and is otherwise read from the text: "not found" is 404, a permission refusal is 403, "already" or "duplicate" is 409, a token or session problem is 401, and anything else is 400. Check status in the body as well as the status code.

Status	Meaning
400	The request was refused: a missing or malformed field, an unknown key, a value out of range.
401	No token, a token that is invalid, expired or revoked, or no valid companyid header.
403	The token lacks the scope, the person's role lacks the permission, or the token may not use the route.
404	The thing does not exist, or the caller may not see it. The two are answered alike on purpose.
409	The request conflicts with what is stored.
429	Rate limited. See Rate limiting.
500	The server failed. The body carries status: false.