First stop when an operator hits an unfamiliar error code. The companion Error Codes page lists every code with its HTTP status, envelope type, and JSON shape; this page adds the operator action and the erectl command that diagnoses it further.
Overview
Only codes that the router emits as
error.code string values are listed. The
public envelope shape is
{"error": {"message", "type", "code", "param"}};
code is optional and many controller errors
omit it, so always cross-check the envelope
type when code is missing.
How to Read This Page
Code, the value in the
error.code field of the router's JSON
response.
Operator action, the single next
step a reasonably experienced operator takes.
Diagnostic, the erectl command to
run if the action fails or you need more context.
Where no dedicated diagnostic command exists yet, the row
notes "(no dedicated diagnostic)" rather than inventing
one. Capture the x-request-id response header
on every failed call, it is the only correlation handle
the router exposes to clients.
Scope & Auth
Note: scope_insufficient is emitted by three
distinct middlewares
(ManagementScopeMiddleware,
InferenceScopeMiddleware, and
ExecScopeValidator) with envelope
type=authentication_error. The same string
code therefore covers management-API, inference-API, and
exec-tool scope gaps; the envelope
message field disambiguates which surface
rejected the call.
Code
Operator Action
Diagnostic
scope_insufficient
Re-issue the key with the required scope, or switch to a key that already carries it. Read the envelope message to see whether management, inference, or exec scope was missing.
erectl keys
cross_project_access
The key belongs to a different project than the resource. Confirm the project_id path segment matches the key's owning project's external ID (ws_-prefixed for workspaces).
erectl keys <key-id>
project_not_found
The project external ID in the path does not exist or is not visible to the caller. Verify the ID with the operator who issued the key.
erectl project members list
signing_public_key_required
The endpoint enforces signed requests; attach the registered Ed25519 public key to the API key before retrying.
erectl keys <key-id>
insufficient_quota
Project credit budget is exhausted. Top up credits or wait for the next billing window.
erectl settings get
billing_delinquent
Billing is past due. Resolve invoices before further inference calls are accepted.
erectl settings get
Agents
Note: enrollment failures
(duplicate name, manifest validation, candidate rejection)
surface as HTTP-status signals on
/v1/enroll/refresh rather than as
error.code string values. There is no
machine-readable agent_* code for offline
agents; absence shows up as missing rows in
erectl agents or as
exec_tool_not_found /
tool_executor_unavailable at execution time.
Code
Operator Action
Diagnostic
agent_not_found
Confirm the agent ID. If the agent was decommissioned, re-enroll or pick another agent in the workspace.
erectl agents
candidate_not_found
The discovery candidate has already been approved, rejected, or expired. List current candidates and decide on a fresh one.
erectl agents candidates list <agent-id>
Workspaces & Models
Code
Operator Action
Diagnostic
workspace_not_found
Verify the workspace external ID (ws_-prefixed); confirm the workspace was not deleted.
erectl workspaces list
model_not_found
The model id is unknown to the router. Re-target the request at a model that exists in the catalog.
erectl models
endpoint_inactive
The endpoint is provisioned but not currently serving. Re-provision it or pick an active endpoint.
erectl endpoints show <endpoint-id>
endpoint_restricted
The endpoint is gated by an allowlist or quota the caller does not satisfy. Update the endpoint's restrictions or use a different endpoint.
erectl endpoints show <endpoint-id>
endpoint_task_mode_mismatch
The endpoint's task_mode (chat, embedding, reranking, etc.) does not match the request's surface. Re-issue the request against an endpoint whose task mode matches.
erectl endpoints show <endpoint-id>
model_not_scoring
No worker for this model is currently scoring as ready. Wait for provisioning or scale the fleet.
erectl endpoints list
invalid_tier
The requested service tier is not configured for this endpoint. Pick a tier the endpoint advertises.
erectl endpoints show <endpoint-id>
Execution
Code
Operator Action
Diagnostic
exec_tool_not_found
The tool name does not resolve in the workspace's effective manifest. Verify the spelling and that an EEM publishing the tool is bound to the workspace.
erectl exec tools
tool_not_mcp_visible
The tool exists but is not exposed to MCP clients in this workspace. Adjust the workspace tool visibility or invoke through the agentic-loop surface instead.
erectl exec tool-show <tool>
tool_executor_unavailable
No online EEM can serve this tool. Verify EEM health, then enroll an additional EEM or scale the fleet.
erectl agents
capacity_exceeded
The fleet is saturated. Wait, retry with backoff, or add capacity.
erectl exec list
rate_limit_exceeded
Back off; honor the Retry-After response header and the retry_after field in the error envelope.
erectl settings get
context_length_exceeded
Request exceeds the model's context window. Compact the conversation, drop earlier messages, or pick a model with a larger context.
erectl models
Approvals
Code
Operator Action
Diagnostic
approval_not_found
The approval id is unknown or has been purged. List current approvals and retry against a live id.
erectl approvals list
approval_not_pending
The approval has already been approved, rejected, or timed out. Inspect its terminal state; re-issue the originating invocation if a new decision is needed.
erectl approvals show <id>
Lifecycle
Code
Operator Action
Diagnostic
invocation_not_found
The invocation id is unknown or has been pruned by retention. Confirm the id and the retention window.
erectl exec list
invocation_terminal
The invocation is already in a terminal state; the requested transition (for example cancel) is a no-op.
erectl exec show <id>
internal_error
Capture the x-request-id response header (not a body field) and the timestamp, then report to the platform team. The router does not surface a body-level request id; the header is the only correlation handle.
(no dedicated diagnostic; provide the x-request-id header value)
