Run errors

Every code a failed run's error object can carry, whose side it's on, whether it's retryable, and the fix.

A run that fails carries an error object on runs_get, runs_list, the inline result of run, and GET /v1/runs/{id}, shaped {code, providerStatus, message, requestId, whoseError, retryable, retryHint}. See Errors: failed runs for the shape. A failed run is charged $0 or the provider’s evidenced cost, and any remaining hold is released.

whoseError is provider, gateway or customer. retryable: true means the same run, same input, same idempotency key can succeed if you try again later; it does not mean the same key re-runs it (the same key always replays the settled result, never charges twice). To actually retry a failed run, use a new idempotency key.

provider_error

The provider answered with an error response (a non-2xx status). Whose error: provider. Retryable: yes. Fix: retry with a new idempotency key. If it keeps failing, the provider is down or rejecting the call; try a different endpoint for the same job (fallback does this automatically, see Fallback).

provider_reported_error

The provider answered 200 OK but the response body itself says the call failed. Whose error: provider. Retryable: yes. Fix: read providerMessage on the run for the provider’s own text, then retry if it looks transient. See Fallback.

timeout

The provider did not respond in time. Whose error: provider. Retryable: yes. Fix: retry; provider timeouts are usually short-lived. See Fallback.

rate_limited

The provider rate-limited this request. Whose error: provider. Retryable: yes. Fix: wait, then retry with a new idempotency key. See Idempotency.

auth_error

The credential connected for this provider was rejected. Whose error: customer. Retryable: no. Fix: reconnect or rotate the credential for this provider on /connections, then retry. See Bring your own provider key.

invalid_response

The provider returned a response looot could not parse. Whose error: provider. Retryable: yes. Fix: retry; if it persists, report it with the requestId, since the provider’s response shape may have changed. See Support.

unsupported_response_type

The provider returned a response type this endpoint’s contract can’t handle (for example binary audio where JSON was declared). Whose error: provider. Retryable: no. Fix: report it with the requestId; this needs a catalog fix, not a retry. See Support.

response_too_large

The provider’s response was larger than looot allows. Whose error: provider. Retryable: no. See Fallback.

redirect_blocked

The provider tried to redirect the request, which looot blocks. Whose error: provider. Retryable: no. See Fallback.

output_mapping_error

The provider succeeded, but looot couldn’t project the result into the output shape you asked for. Also seen as output_mapping_projection_failed. Whose error: gateway. Retryable: no. Fix: retry with output.mode: "raw", or report the mapping. See run.

endpoint_not_found

The requested endpoint id doesn’t exist. Whose error: customer. Retryable: no. Fix: looot search "..." or MCP search_catalog to find a current endpoint id, then retry. See search.

eligibility_blocked

This workspace isn’t eligible to run this endpoint. Whose error: customer. Retryable: no. See Access.

activation_blocked

This endpoint hasn’t finished activation on looot’s side yet. Whose error: gateway. Retryable: no. Fix: pick another endpoint for the job; this one isn’t runnable yet. See search.

credential_denied

No usable credential was available for this run (the endpoint needs your own connected account and you don’t have one). Whose error: customer. Retryable: no. Fix: connect an account for this provider on /connections, or wait for platform-supplied access. See Bring your own provider key.

platform_key_missing

No platform key is configured for this provider yet, and you have no connection of your own. Whose error: gateway. Retryable: no. Fix: connect your own account for this provider, or ask for it with capability_request. See Bring your own provider key.

platform_auth_incompatible

A platform key exists but its auth can’t be applied to this endpoint. Whose error: gateway. Retryable: no. Fix: connect your own account for this provider instead, or report it. See Bring your own provider key.

credential_placement_unsupported

The credential’s fields couldn’t be placed in this endpoint’s request body. Whose error: gateway. Retryable: no. Fix: report it with the requestId. See Support.

budget_exceeded

This run would exceed the workspace’s budget policy. Whose error: customer. Retryable: no. Fix: raise the budget, or wait for the next budget window. See Cost cap.

insufficient_balance

The workspace balance can’t cover this run’s estimated cost. See REST errors: insufficient_balance for the full shape; this run-level version carries the same code when a run settles this way after being admitted. Whose error: customer. Retryable: no. Fix: top up, then retry with a new idempotency key. See Top up.

provider_disabled

This endpoint is switched off right now (a provider-wide or endpoint-scoped disable). Whose error: gateway. Retryable: no. Fix: pick another endpoint for the same job; search and discover list the ones that run now by default. See search.

provider_draining

This endpoint is draining and not taking new runs. Whose error: gateway. Retryable: no. Fix: retry later, or pick another endpoint for the same job. See Fallback.

connection_not_found

No connection exists for this provider. Whose error: customer. Retryable: no. Fix: connect an account for this provider on /connections, then retry. See Access.

connection_invalid

Your connected account for this provider couldn’t be used (also seen as token_resolve_failed, same message). Whose error: customer. Retryable: no. Fix: reconnect the account for this provider on /connections, then retry. See Bring your own provider key.

provider_http_error

The provider answered, but not with a 2xx status; providerStatus and providerMessage carry the provider’s own status and body text. Whose error: provider. Retryable: yes. Fix: retry; if it keeps failing, the provider is rejecting or down. See Fallback.

fetch_failed

looot couldn’t reach the provider at all (DNS, TLS, connection reset). Whose error: gateway. Retryable: yes. Fix: retry; report it with the requestId if it persists. See Fallback.

connection_unusable

Your connected account for this provider is pinned to the run but can no longer be used (revoked or gone). Whose error: customer. Retryable: no. Fix: reconnect the account on /connections. See Bring your own provider key.

contract_invalid

The endpoint’s stored dispatch contract couldn’t be used. Whose error: gateway. Retryable: no. Fix: report it with the requestId; pick another endpoint for the job meanwhile. See Support.

route_denied

The workspace’s route policy denied every candidate for this run. Whose error: gateway. Retryable: no. See Support.

no_route_candidate

No route candidate was available for this run. Whose error: gateway. Retryable: no. Fix: retry later, or use a different provider for this capability. See Fallback.

capacity_exhausted

Capacity for this provider or connection is exhausted right now. Whose error: gateway. Retryable: yes. Fix: retry shortly; capacity frees up as in-flight runs settle.

cancelled_before_dispatch

The run was cancelled (via runs_cancel or runs cancel) before it reached the provider. Whose error: customer. Retryable: no. See runs_cancel.

cancellation_requested_after_dispatch

Cancellation was asked for after the provider was already dispatched; the outcome is unconfirmed. Whose error: customer. Retryable: no. Fix: check runs_evidence for what actually happened before retrying. See runs_evidence.

runtime_store_replaced_before_dispatch

The run was abandoned by a runtime restart before it reached the provider (also seen as restart_recovered_before_dispatch). Whose error: gateway. Retryable: yes. Fix: retry the run. See Idempotency.

See Job refusals for route_capped and route_no_fit, the two codes a job:<id> run gets when no provider was ever called, and for the result.code values on a job run’s failed body.