Errors

The shapes an error takes in the CLI, REST API, MCP tools and failed runs, plus a lookup table for every code and its fix.

Every error carries a stable code you can match on, a plain message, and, where there is one thing to do, a fix. Quote the requestId (or a run’s runId) when you ask for help.

There are four places an error can show up, and each has its own shape.

CLI stderr

On a terminal, looot prints one line, then the fix:

The workspace balance is too low to reserve this run's estimated cost. (request req_...)
Fix: Add credits at https://looot.ai/usage?top_up=1

Piped, or with --format json or --format jsonl, it prints one JSON object on stderr and exits with code 1:

{
  "code": "insufficient_balance",
  "message": "The workspace balance is too low to reserve this run's estimated cost.",
  "retryable": false,
  "status": 402,
  "requestId": "req_...",
  "fix": "Add credits at https://looot.ai/usage?top_up=1",
  "error": { "code": "insufficient_balance", "message": "..." }
}

Nothing on stdout mixes with an error: stdout carries only a command’s result. Ctrl+C prints Cancelled. and exits with code 130. See CLI command reference and CLI errors for the local, network and file errors that never reach the gateway.

REST errors

GET/POST/etc against https://api.looot.ai answer with an HTTP status and a JSON body:

{ "error": { "code": "idempotency_conflict", "message": "...", "requestId": "req_..." } }

Some routes add fields next to error. POST /v1/runs at 402 adds balanceMicros, estimatedCostMicros and a topUp object with a checkout link; POST /v1/runs at 429 adds inflight, limit and retryAfterSeconds. See REST errors.

A 201 from POST /v1/runs can still carry "status": "failed" or "status": "blocked", for example when the input fails the endpoint’s own schema. Check status and error on the run body, never the HTTP status code alone.

MCP tool errors

A failed tool call returns isError: true, with the same object in both content[0].text (as compact JSON) and structuredContent.data:

{
  "code": "idempotency_conflict",
  "message": "This idempotencyKey was already used with a different body. Reuse the exact same body to replay the original, or pick a new idempotencyKey for a new request.",
  "retryable": false,
  "requestId": "req_...",
  "error": "idempotency_conflict"
}

message always says what to do next. error repeats code as a plain string, kept for a caller written against the older { error: "<code>" } shape. Arguments that don’t match a tool’s schema come back as validation_error naming the field. Anything unexpected comes back as internal_error with a requestId to report. See MCP errors.

Failed runs

When a run itself fails, the run record carries an error object, whatever surface fetched it (runs_get, runs_list, the inline result of run, or GET /v1/runs/{id}):

{
  "code": "provider_error",
  "providerStatus": 502,
  "message": "The provider returned an error response.",
  "requestId": "req_...",
  "whoseError": "provider",
  "retryable": true,
  "retryHint": "Retry the run; if it keeps failing, the provider itself is rejecting or down."
}

whoseError says whose side the problem is on: provider, gateway or customer (you). A failed run settles at $0 (or the provider’s evidenced partial cost) and any remaining hold is released. A job:<id> run that never called a provider gets its own two codes, route_capped and route_no_fit; see Job refusals for those and for the result.code values a job: run’s failed body carries. See Run errors for the full list.

Every code

See Money: free calls and failures for how a failed or refused run is charged.