Errors and limits

A failed call returns a non-2xx HTTP status and a JSON body. The SDK reads both and throws one of three typed errors; the CLI catches those and turns them into a message on stderr and an exit code. Writing your own client against the same endpoints, read the status first — it tells you which of the three you have before you parse anything else.

{
  "status": "ERROR",
  "errors": ["a plain-language reason"]
}

The workspace does not have enough credits for the call. This is the one failure worth checking for by type rather than by message, because the body carries numbers you can act on directly.

{
  "status": "ERROR",
  "code": "insufficient_credits",
  "errors": ["insufficient_credits"],
  "creditsShort": 1200,
  "balance": 300
}

creditsShort

How many more credits the call needed.

balance

The workspace's balance at the time of the call.

Top up the workspace and retry the same call unchanged.

Too many requests too quickly. Back off for the stated duration.

HTTP/1.1 429 Too Many Requests
Retry-After: 30

{ "results": { "retryAfterSeconds": 30 } }

The wait is read from whichever of the header or the body states it; either can carry the number. When neither does, wait at least one second before trying again.

Everything else — a bad argument, a share that does not exist, an edit name that does not match anything in the project, a file that failed to upload — arrives as a plain error with the HTTP status it actually failed at and the reason in errors[0].

• 400/404 from a command. Something in the call was wrong — an id that does not resolve, or an edit name that does not match one in the project. The message says which.
• A failed upload. The CLI reports the file that failed and marks it failed on the server side so the import terminates cleanly rather than hanging on a part that will never arrive.
• A prompt run that ends other than done. failed and cancelled are real outcomes, not transport errors — the run reached the server and ended badly.refused means the server declined to start it at all; the reason is on the event.

0

Success.

1

A general failure — the message is on stderr.

2

Out of credits, or a prompt run ended refused or failed. Worth a distinct code in a script: this is the case where retrying immediately will not help.

• 402 — top up, then retry. The identical call succeeds once the balance covers it.
• 429 — wait, then retry. Honour the stated delay rather than retrying immediately in a loop.
• 401 — do not retry, fix the key. A revoked or malformed key fails the same way every time. See Authentication.
• A bad argument — correct it, then retry. The same call fails the same way until the id or name it names is fixed.
• An upload or network failure — retry once. If it repeats, stop and report it rather than looping.