--- title: Run errors description: Every code a failed run's error object can carry, whose side it's on, whether it's retryable, and the fix. sidebar: label: Runs --- A run that fails carries an `error` object on [`runs_get`](/mcp-tools/runs-get), [`runs_list`](/mcp-tools/runs-list), the inline result of `run`, and `GET /v1/runs/{id}`, shaped `{code, providerStatus, message, requestId, whoseError, retryable, retryHint}`. See [Errors: failed runs](/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](/concepts/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](/concepts/fallback). ### timeout The provider did not respond in time. Whose error: provider. Retryable: yes. Fix: retry; provider timeouts are usually short-lived. See [Fallback](/concepts/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](/concepts/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](/guides/bring-your-own-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](/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](/support). ### response_too_large The provider's response was larger than looot allows. Whose error: provider. Retryable: no. See [Fallback](/concepts/fallback). ### redirect_blocked The provider tried to redirect the request, which looot blocks. Whose error: provider. Retryable: no. See [Fallback](/concepts/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`](/mcp-tools/run). ### endpoint_not_found The requested endpoint id doesn't exist. Whose error: customer. Retryable: no. Fix: `looot search "..."` or MCP [`search_catalog`](/mcp-tools/search-catalog) to find a current endpoint id, then retry. See [`search`](/mcp-tools/search). ### eligibility_blocked This workspace isn't eligible to run this endpoint. Whose error: customer. Retryable: no. See [Access](/concepts/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`](/mcp-tools/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](/guides/bring-your-own-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`](/mcp-tools/capability-request). See [Bring your own provider key](/guides/bring-your-own-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](/guides/bring-your-own-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](/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](/money/cost-cap). ### insufficient_balance The workspace balance can't cover this run's estimated cost. See [REST errors: insufficient_balance](/errors/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](/money/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`](/mcp-tools/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](/concepts/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](/concepts/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](/guides/bring-your-own-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](/concepts/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](/concepts/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](/guides/bring-your-own-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](/support). ### route_denied The workspace's route policy denied every candidate for this run. Whose error: gateway. Retryable: no. See [Support](/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](/concepts/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`](/mcp-tools/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`](/mcp-tools/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](/concepts/idempotency). See [Job refusals](/errors/job-refusals) for [`route_capped`](/errors/job-refusals#route_capped) and [`route_no_fit`](/errors/job-refusals#route_no_fit), the two codes a `job:` run gets when no provider was ever called, and for the `result.code` values on a job run's failed body.