Karta uses conventional HTTP status codes. The body is JSON with aDocumentation Index
Fetch the complete documentation index at: https://docs.karta.sh/llms.txt
Use this file to discover all available pages before exploring further.
detail or
an error/reason pair.
Status codes
| Status | Meaning | Body |
|---|---|---|
200 | Success — accumulated response, or the start of an SSE stream. | response object / SSE |
201 | Resource created (session, release). | the resource |
202 | Accepted — async work queued (e.g. a Managed Agents event). | { "accepted": true } |
401 | Missing or invalid credential. | { "detail": "Unauthorized" } |
402 | Budget exhausted — checked before running anything. | { "error": "budget_exhausted", "reason": "…" } |
403 | Forbidden — e.g. a session token scoped to another project. | { "detail": "…" } |
404 | Not found, or belongs to another org (default-deny). | { "detail": "…" } |
409 | Conflict — e.g. no active/materialized release for a project. | { "detail": "…" } |
422 | Validation failed, or a BYOK key was rejected by the provider. | { "error": "byok_key_rejected", "provider": "…", "message": "…" } |
503 | Service unavailable — harness down or breaker open. | { "detail": "…" } + Retry-After |
402 — budget exhausted
When an org hits a budget cap, the data plane returns402 before running the turn:
Errors during a stream
Once an SSE stream has started (200 already sent), failures arrive as an
error event rather than an HTTP status —
because the status line is already on the wire:
error events for mid-stream problems
(provider rejection, harness failure).
503 and retries
A503 carries a Retry-After header. The data plane’s control-plane key
validation fails closed on outages — repeated failures open a short circuit
breaker and return 503 rather than letting unvalidated requests through.
Back off and retry.