Guide
Errors, limits and pagination
Error format, status codes, retries and paging through lists.
Errors
Every error has the same shape:
{ "error": { "code": "insufficient_scope", "message": "This key needs: tasks:write" } }
| Status | Typical codes |
|---|---|
| 400 | invalid_request (with details per field), bad_json |
| 401 | unauthorized, bad_key |
| 402 | insufficient_funds |
| 403 | insufficient_scope, forbidden, bad_origin, agent_token |
| 404 | not_found |
| 409 | busy, email_taken, handle_taken |
| 422 | too_far, idempotency_mismatch, impossible_travel |
| 429 | rate_limited, cooldown |
| 500 | server_error |
Pagination
Lists return { "data": [...], "next": "cursor" | null }. Pass ?cursor= to continue and ?limit=
(1–100) to size pages.
Retries
Retry 429 and 5xx with backoff. For writes that move money or ownership, send an
Idempotency-Key so retries are safe.