Guides
Errors & Edge Cases
Complete error catalog and async failure modes for production integrations.
Audience
Developers implementing retries and failure handling.
Complete error catalog and async failure modes for production integrations. Branch on error.code: messages are stable but intended for humans, not programmatic matching.
All errors use the envelope { "error": { "code": "…", "message": "…" } }.
Error catalog#
| Code | HTTP | When |
|---|---|---|
unauthorized | 401 | Invalid, missing, revoked, or expired API key |
insufficient_scope | 403 | Key lacks required scope |
forbidden | 403 | Not entitled to workflow or run (non-leaky) |
not_found | 404 | Unknown workflow or run, or cross-tenant run |
method_not_allowed | 405 | The resource does not support the HTTP method |
idempotency_conflict | 409 | Idempotency key reused with a different request |
spend_cap_reached | 402 | API key spend cap exceeded (sync, before run created) |
rate_limited | 429 | 60 POST /runs requests per minute per key |
invalid_json | 400 | Request body is not valid JSON |
missing_workflow | 400 | POST /runs without a workflow id |
invalid_inputs | 400 | Missing, unknown, conflicting, or incorrectly typed inputs |
invalid_request | 400 | Query parameter or pagination value is invalid |
invalid_cursor | 400 | Invalid SSE Last-Event-ID or afterSequence |
internal_error | 500 | Unexpected server error (no internals leaked) |
Async failures after 202#
POST /runs returns 202 before wallet or bundle funding is finalized. If the account lacks funds, the run row is created then fails during preparation. Poll GET /runs/{id} and handle status: failed: there is no synchronous 402 for insufficient wallet balance. Spend cap breaches are the opposite: they return 402 synchronously and no run id is created.
The full condition-by-condition contract, including records, charging, earnings, and retries, is maintained in Create Run: canonical funding and acceptance behavior.
Run model edge cases#
- free: runnable via wallet path when entitled.
- per_run: wallet or bundle charged at trigger.
Was this useful?
Your response helps us improve the documentation.