Skip to main content

Errors

Every non-2xx response carries the same envelope:

{
"error": {
"code": "PROJECT_PAUSED",
"message": "...",
"hint": "Resume the project with `POST /v1/projects/{project_id}/resume` once whatever paused it is resolved; ...",
"meta": {}
}
}

code, message and hint are always present. Branch on code, which is stable; message and hint are for people and agents and may change. message says what went wrong; hint says what to do about it, naming only routes of this API. meta carries structured context when there is any. A managed model provider's own answer is not relayed (Generations → Provider errors).

The same error reaches every surface: a REST response, an SSE error frame, an MCP tool result's structuredContent, and an agent's tool result when a tool call it makes is refused.

Every code is UPPER_SNAKE. Where naturali refuses for a reason the upstream runtime also refuses for, it answers the runtime's code (FORBIDDEN, RESOURCE_NOT_FOUND, VALIDATION_FAILED, QUOTA_EXCEEDED), so a caller branches the same way whichever side refused.

Codes common to every module​

StatuscodeMeans
400VALIDATION_FAILED, or a more specific codeThe request is malformed; message says which field.
401UNAUTHORIZEDMissing, malformed, expired or revoked credential — see Authentication.
402INSUFFICIENT_CREDITThe billing owner's balance cannot pay for this work — see Users → Plan and credit.
403FORBIDDENThe credential's scope or the caller's role excludes the action.
403PLAN_LIMIT_REACHED, PLAN_FEATURE_NOT_INCLUDEDThe billing owner's plan excludes it. meta.resource or meta.feature names what.
404RESOURCE_NOT_FOUND, or the runtime's ownThe resource does not exist, or its project is not one you belong to.
409VariesA conflicting state, such as a duplicate or a paused project.
429QUOTA_EXCEEDED, or a more specific codeA rate limit or a quota — see Rate limits.
502UPSTREAM_UNAVAILABLEnaturali could not complete the call upstream; see below.

Each operation's page in the API Reference lists the codes it adds, and a module page explains any whose cause is not obvious.

502 UPSTREAM_UNAVAILABLE​

A 502 UPSTREAM_UNAVAILABLE is naturali standing in for the upstream runtime, and its meta says what the runtime answered: upstream_status (the HTTP status) and upstream_code (the runtime's own error code) when it answered at all, and neither when nothing reached it. That separates a runtime that refused from a request that never got there.

A server error that does not come from the runtime itself, such as an infrastructure page in front of it, is answered the same way: a 502 UPSTREAM_UNAVAILABLE whose meta carries only upstream_status, never the page.

Reading an error in each client​

The CLI prints the envelope to stderr with its status and exits 1. The SDK never throws on a non-2xx response; it resolves to { data, error }. With curl, add --fail-with-body to make the exit status reflect it.

naturali get-agent \
--project-id proj_V1StGXR8Z5jdHi6B \
--agent-id agent_missing || echo "failed"