API

Errors and limits

Response codes of the Ghosty Studio API, what each one means and how to retry; sizes and caps.

Updated 2026-09-16

Codes

Code	Body	What to do
`202`	`{ turnId, key, estado, enCola, reemplazoAnterior, repetido }`	The turn was accepted, not finished. Listen to the . `enCola` (queued) > 0 = there are turns ahead. `repetido` (repeated) = you had already sent that `turnId`, it was not duplicated. `estado` = state; `reemplazoAnterior` = replaced the previous one.
`400`	`{ error }`	Invalid body: missing `content`, `id`/`optionId`, empty model… Don't retry without changing it.
`401`	text	No token or expired. Refresh and retry once.
`402`	`{ error: "quota_exhausted" \| "trial_expired" \| "own_key_required", message }`	Allowance exhausted, trial expired or a model that requires your own key. The `message` is for display.
`403`	text	A scope is missing. Don't retry: request the scope at the next login.
`404`	text or `{ error: "not_found" }`	The agent isn't yours, or the resource doesn't exist. Someone else's agent responds 404 and not 403, on purpose.
`405`	`{ error: "method_not_allowed" }`	Wrong method.
`409`	`{ error: "agente_no_acp", motor }`	The agent doesn't speak this API's conversation protocol (engine without ACP). `motor` = engine.
`413`	`{ error: "audio demasiado grande" }`	Audio or file above the cap ("audio too large").
`503`	`{ error: "reiniciando" }` + `Retry-After: 10`	Deploy in progress ("restarting"). Retry with the same `turnId` after the `Retry-After`: it doesn't duplicate.

Idempotency

POST …/messages accepts a turnId of yours (UUID). If you repeat the request with the same turnId — because of a timeout, a 503, a bad network — the server replies repetido: true and doesn't create a second turn. Always use it.

Concurrency

An agent runs one turn at a time per conversation. A new message in a conversation with a turn in progress stops the previous one and replaces it (reemplazoAnterior: true): it is the way to correct the agent mid-work. Only whoever requested the turn can replace it. Different conversations of the same agent run in parallel up to the plan's cap; those waiting for a machine count in enCola.

Sizes

What	Cap
Attachments per message	8
Audio for `POST /api/v2/me/stt`	per plan; exceeding it returns `413`
Signed URL of a file	6 hours; request it again with `GET /api/v2/me/files/:id`
OAuth2 authorization code	60 s
Access token	1 h
Refresh token	90 days, rotates on every use
Unanswered permission	10 min → denied

Rate

There is no published requests-per-second limit in beta; the real cap is the plan's token allowance and the machines awake at once. If you see 429, honor Retry-After.

← Previous

Events (SSE)

Changelog