REST API / guide 18 of 19
API responses use a small, predictable envelope. Check ok before reading data; failed requests return an error code and a human-readable message.
// Success
{ "ok": true, "data": { "items": [] } }
// Error
{ "ok": false, "error": {
"code": "invalid_actor_scope",
"message": "Every scoped actor must belong to your workspace"
} }| Status | Typical meaning | Client action |
|---|---|---|
| 400 | Input or Actor scope is invalid | Fix the request; do not retry unchanged. |
| 401 / 403 | Missing, invalid, or insufficient credential | Refresh the session or use a credential with the required scope. |
| 404 | Resource is not in the selected workspace | Check the identifier and workspace selection. |
| 409 | Workspace state or plan prevents the operation | Resolve the setup or plan requirement first. |
| 429 / 503 | Rate limit or provider/queue is temporarily unavailable | Back off and retry only when the operation is safe to repeat. |
Treat write endpoints as potentially asynchronous: a successful queue response means the job was accepted, while the operation status is the source for its eventual result.