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 may return 202 before funding checks finish. If the account lacks funds, polling later reports status: failed; there is no synchronous 402 for insufficient wallet balance. Spend-cap breaches return 402 immediately and do not include a run id.
The condition-by-condition contract for charging and retries is maintained in Create Run: 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.