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
| Status | code | Means |
|---|---|---|
400 | VALIDATION_FAILED, or a more specific code | The request is malformed; message says which field. |
401 | UNAUTHORIZED | Missing, malformed, expired or revoked credential — see Authentication. |
402 | INSUFFICIENT_CREDIT | The billing owner's balance cannot pay for this work — see Users → Plan and credit. |
403 | FORBIDDEN | The credential's scope or the caller's role excludes the action. |
403 | PLAN_LIMIT_REACHED, PLAN_FEATURE_NOT_INCLUDED | The billing owner's plan excludes it. meta.resource or meta.feature names what. |
404 | RESOURCE_NOT_FOUND, or the runtime's own | The resource does not exist, or its project is not one you belong to. |
409 | Varies | A conflicting state, such as a duplicate or a paused project. |
429 | QUOTA_EXCEEDED, or a more specific code | A rate limit or a quota — see Rate limits. |
502 | UPSTREAM_UNAVAILABLE | naturali 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.
- CLI
- SDK
- curl
naturali get-agent \
--project-id proj_V1StGXR8Z5jdHi6B \
--agent-id agent_missing || echo "failed"
const { data, error } = await naturali.agents.getAgent({
path: { project_id: 'proj_V1StGXR8Z5jdHi6B', agent_id: 'agent_missing' },
});
if (error) {
console.error(error.error.code, error.error.message);
}
curl --fail-with-body \
https://api.naturali.ai/v1/projects/proj_V1StGXR8Z5jdHi6B/agents/agent_missing \
-H "Authorization: Bearer $NATURALI_TOKEN"