Error codes
An error always has the shape:
{ "code": "validation_failed", "message": "input tidak valid", "fieldErrors": { "route": "channel.route_invalid" } }code is stable and safe for programs to handle. message is only for human reading. fieldErrors (optional) maps field names to error codes.
| Status | code (examples) |
Meaning |
|---|---|---|
| 401 | unauthorized |
The header is empty or is not Bearer tpat_…. |
| 401 | auth.invalid_token |
The token is unknown, revoked, or expired. |
| 403 | forbidden |
The token lacks permission for that action or object. |
| 403 | pat.not_allowed |
A route outside /api/v1/workspaces/.... |
| 403 | quota.channels_exceeded, quota.devices_exceeded, quota.workspaces_exceeded |
The workspace owner’s quota has been reached. |
| 404 | channel.not_found, device.not_found, … |
It does not exist, or the token may not read it (not distinguished). |
| 409 | config.not_deliverable, dashboard.version_conflict, … |
A state conflict, for example a storage rule already exists or a dashboard version is stale. |
| 422 | validation_failed |
Invalid input; see fieldErrors. |
| 429 | rate_limited |
Too frequent (a rate limit). |
| 503 | backend_unreachable |
The web tier cannot reach the backend. |
Codes you will often see
Section titled “Codes you will often see”| Code | Cause and handling |
|---|---|
workspace.last_admin |
A workspace must have at least one active Admin. Make another member an Admin first. |
rule.cannot_enable |
The rule is incomplete or invalid; fix the per-node errors, then enable it. |
rule.lua_missing_logic_function |
A Lua script must have the form function logicFunction() … end and return logicFunction(). |
config.no_channel / config.not_deliverable |
There is no destination channel followed (subscribed) by the device or its gateway. |
config.serial_required |
The device has no Serial yet; fill it in first. |
device.gateway_has_children |
The gateway is still used by other devices; release them first. |
group.cycle, group.too_deep, group.has_children |
The group hierarchy is invalid or the group still has children. |
invitation.email_mismatch |
Registration through an invitation must use the same e-mail as the invitation. |
bootstrap.invalid_proof, bootstrap.disabled |
The proof is wrong (or the workspace/External ID/nonce is wrong), or the configuration is disabled. |
report.busy, report.rows_limit, report.pdf_unavailable |
The report is running, the data exceeds the row limit, or the PDF service is unavailable. |
workspace.delete_not_owner, workspace.confirm_mismatch |
Only the owner can delete, and the confirmation must be the route. |
Tip: show message to end users, but base your program’s branching on code.