error code (distinct from the management API’s error envelope), and each one tells the agent what to do next, usually with a pre-built dashboard link.
Every definite verdict carries the x-should-retry: false header: retrying unchanged will not succeed — the fix is the named remediation. Only the transient responses omit it: gateway_restarting, rate_limited, and the 502 internal errors.
Summary
The two 409s and the 404 belong to the multiple accounts protocol, which documents their bodies and the
x-onecli-connection-id retry contract in full.
Access errors
access_restricted
A credential for this host exists in the project, but the requesting agent holds no grant for it. The upstream 401/403 status is preserved; manage_url opens the app’s connections page, where each account’s Agent access dialog attaches it to agents.
app_not_connected
The host belongs to a known app, but no account of it is connected. connect_url opens the connect flow. A second variant covers known API hosts with no registered provider (for example an unregistered Google API on www.googleapis.com) — it carries hostname instead of provider and its connect_url opens the “Request an app” dialog.
credential_not_found
The host is not a known app and no secret matches it. secret_url is a pre-built create link with the host and path pre-filled; the message documents query parameters the agent can append before handing it to the user — &name= for a display name, &header= / &format= to describe a custom auth header, or ¶m= for query-parameter auth.
Policy errors
blocked_by_policy
A named rule blocked the request. At project scope the block comes from the agent’s own grant (changeable on the agent’s pages); an organization rule’s block can only be changed by an org admin. dashboard_url opens the agents page.
blocked_by_default_policy
No rule matched under a deny-by-default posture — there is no rule_name because no rule decided; the request failed because nothing allowed it. The usual fix is attaching the credential the agent needs.
app_unavailable
The organization’s app-availability allowlist excludes this app for the project. Only an organization admin can change availability, so there is no per-project link.
resource_access_denied
A session policy on the connection restricts which resources it may touch (for example, GitHub {"repositories": ["acme/api"]}), and the request targeted something outside the list.
Approval errors
manual_approval_denied
A request held for manual approval was denied by the reviewer, or expired unanswered. approval_id identifies the decision in the audit log.
gateway_restarting
The gateway shut down while holding the request for approval. Nobody decided anything — this is deliberately not the 403 a denial produces, so agents don’t stop retrying something that was never refused. It is the one gateway error that is safe to retry as-is; a retry-after: 1 header is set.
Limit errors
rate_limited
An allow rule’s rate limit was hit. Retry after the retry-after header (seconds); limit echoes the cap.
Cloud plan limits
On OneCLI Cloud, three additional errors can appear:quota_exceeded (429 — the plan’s monthly integration-call quota), budget_exceeded (429 — a partner-set spend cap on an LLM key), and claim_required (403 — the organization must be claimed before this credential can be used). Each message states the exact limit and the action to take.
Handling in code
The Node SDK ships typed interfaces for these bodies and aparseGatewayError helper that narrows an unknown response body to the right shape — see the SDK reference for a retry example.
Related
- Multiple accounts — the 409/404 disambiguation protocol
- API errors — the management API’s error format and retirement inventory