> ## Documentation Index > Fetch the complete documentation index at: https://docs.orisu.ai/llms.txt > Use this file to discover all available pages before exploring further. # Error codes > Every tool error has a stable `code`, a human `message`, and a `next_action` hint. Use the code to branch and recover automatically. When an Orisu MCP tool fails, the response carries a typed error envelope: ```json theme={null} { "code": "SCOPE_MISSING", "message": "trigger_run requires 'runs:execute' but the bearer carries: agents:read, runs:read", "next_action": "Ask the user to reconnect Orisu and grant 'runs:execute', or use an Orisu API key (pk_live_*) whose scope set includes runs:execute.", "details": { "tool": "trigger_run", "missing": ["runs:execute"], "present": ["agents:read", "runs:read"] } } ``` Branch on `code` to recover automatically. `next_action` is the one-line summary you can present to the user; `details` carries machine-readable context. ## Auth + scoping | Code | Meaning | Recover by | | --------------- | ------------------------------------------ | -------------------------------------------------------------------------------------------------------------------- | | `UNAUTHORIZED` | No bearer token (or invalid) | Re-run the OAuth flow (chat clients) or check the API key (`pk_live_*`). | | `SCOPE_MISSING` | Bearer is valid but lacks a required scope | Re-consent to add the missing scope, or use an API key whose scope set includes it. `details.missing` lists the gap. | | `ORG_NOT_BOUND` | OAuth token isn't bound to a workspace | Open the consent flow again and pick a workspace. | ## Not found | Code | Meaning | Recover by | | ------------------- | ------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- | | `AGENT_NOT_FOUND` | `agent_id` doesn't exist in this org (or was deleted) | `search({ kind: 'agents', query })` to find the right id. | | `RUN_NOT_FOUND` | `run_id` doesn't exist (or was pruned by retention) | `list_runs({ agent_id })` to find a live one; if the workflow needs re-running, `trigger_run` again. | | `APP_NOT_FOUND` | `app_id` isn't a published app in this org | `search({ kind: 'apps', query })` or `orisu://apps`. | | `VERSION_NOT_FOUND` | `version_id` doesn't exist for this agent (or the agent has no graph yet) | Read `orisu://agents/{id}/versions` for the list; for a brand-new agent, `replace_graph` to create the first version. | | `ASSET_NOT_FOUND` | `asset_id` doesn't exist or was trashed | Read `orisu://assets`. | ## Validation | Code | Meaning | Recover by | | --------------------- | ---------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `VALIDATION_FAILED` | The GraphSpec (or an input value) failed validation | `details.errors[]` carries the specific problems — unknown ports and node types include "Did you mean …?" suggestions. Fix and re-run `validate_graph` until `valid: true`. | | `INPUT_TYPE_MISMATCH` | A `trigger_run` input value doesn't match the input node's expected shape | Call `get_run_inputs_schema({ agent_id })` for the exact shape, fix, retry. | | `VERSION_CONFLICT` | The agent was edited between your read and your write (raised when you pass `base_version_id`) | Re-read with `view_agent`, recompute against the latest graph, retry with the fresh `latest_version_id`. | ## Execution | Code | Meaning | Recover by | | ---------------------- | -------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `RATE_LIMITED` | Per-org or per-client rate limit hit | `details.retry_after_seconds` says how long to wait; back off and retry. | | `INSUFFICIENT_CREDITS` | Org credit balance is below the run's estimate | Top up from your Orisu dashboard's billing page, or use a cheaper model — `suggest_model({ kind, use_case })` returns ranked variants with `best_for` guidance; scan down the list for cheaper alternatives. | | `MODEL_PROVIDER_ERROR` | The model errored mid-execution | `details.provider_error` carries the reason. Retry once; if persistent, swap the model variant. | | `RUN_ALREADY_TERMINAL` | `cancel_run` called on a run that's already `completed` / `failed` / `cancelled` | Check `orisu://runs/{id}` for the actual status. | | `IDEMPOTENCY_CONFLICT` | Same idempotency key, different request body | Either change the key or send the original body. | ## Internal | Code | Meaning | Recover by | | ---------------- | ----------------------------------------- | ------------------------------------------------------------ | | `INTERNAL_ERROR` | Something on our side failed unexpectedly | Retry once. If it persists, report the `details.request_id`. | | `BAD_REQUEST` | Request shape is malformed | Re-check the JSON-RPC envelope and tool argument types. | ## Recovery loop (the canonical pattern) The [orisu-workflows skill](/mcp/tools#workflow-skill) ships an "Error recovery playbook" section that the assistant follows automatically. Roughly: 1. Read `error.code` (and `details.step_id` for run-step failures) 2. Branch on the code per the table above 3. Try the suggested recovery once 4. If recovery itself fails, surface the error to the user with the original `next_action` hint For the common cases (scope missing, model error, rate limited) the agent recovers without involving you. ## See also Scopes that drive `SCOPE_MISSING`. Which tools produce which errors.