Errors and limits
Handle validation, authorization, capacity and uncertain writes
The API uses HTTP status to distinguish success from failure. Newer routes return an error object; older routes may return an error string or a validation object. Support both shapes.
{"ok":false,"error":{"code":"actor_required","message":"This API key must be linked to an organization administrator for pipeline authoring or execution.","details":null}}| Status | Response to take |
|---|---|
| 400 | Correct the body, filters or snapshot/version selector |
| 401 | Check the Bearer credential, expiry and revocation |
| 402 | Inspect workspace plan/usage limits; repeating the request cannot increase allowance |
| 403 | Check scope, resource boundary, actor, named grants and policies |
| 404 | Check workspace and resource IDs; some inaccessible resources appear unavailable |
| 409 | Inspect revision, idempotency conflict, references or active work before retrying |
| 410 | An expiring result is no longer usable; start a new authorized query if needed |
| 429 | Honor Retry-After and back off |
| 5xx | Preserve the request identity; determine whether work was accepted before retrying writes |
Request limits include workspace and credential windows. Read returned rate-limit headers when present. A capacity rejection can return 503 with Retry-After; a request-rate rejection and a plan quota are separate limits.
For a failed pipeline dispatch response, retry with its original idempotency key or inspect the known run. For a source write, inspect its operation record and use the recovery action when appropriate. A network timeout is not evidence that no data changed.
Log method, resource IDs, status and safe error fields. Avoid recording API keys, connector passwords or full sensitive records. Workspace activity helps correlate query and operation history.