Error codes

When an Orisu MCP tool fails, the response carries a typed error envelope:

{
  "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 ships an “Error recovery playbook” section that the assistant follows automatically. Roughly:

Read error.code (and details.step_id for run-step failures)
Branch on the code per the table above
Try the suggested recovery once
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.

Authentication

Scopes that drive SCOPE_MISSING.

Tools

Which tools produce which errors.

Get started

Reference

Operations

Auth + scoping

Not found

Validation

Execution

Internal

Recovery loop (the canonical pattern)

See also

Authentication

Tools

​Auth + scoping

​Not found

​Validation

​Execution

​Internal

​Recovery loop (the canonical pattern)

​See also

Authentication

Tools

Auth + scoping

Not found

Validation

Execution

Internal

Recovery loop (the canonical pattern)

See also