Errors
NeuroAPI status codes and error codes, what to do about each, and when to retry.
The public API uses standard HTTP status codes. Error bodies are JSON
with a detail key, except 413, which is plain text. detail comes in
three shapes, so branch on the HTTP status first, then read detail.
Coded - 400, 402, 409, 429, 504, most 403s, and the 422s under Error codes. code is stable
and safe to branch on; message is prose and may be reworded.
{
"detail": {
"code": "mode_not_in_plan",
"message": "Mode 'max' is not available on the 'starter' plan. Upgrade to access it."
}
}Plain - 401 and 503.
{
"detail": "Invalid API key"
}Validation - a 422 caused by a malformed body. Here detail is a
list, described under Validation below.
{
"detail": [{ "type": "missing", "loc": ["body", "prompt"], "msg": "Field required" }]
}detail is not always a string. String(err.detail).toLowerCase() breaks
the first time it sees a 403 or a 429.
Every error response also carries an X-Request-Id header. Quote it
when reporting issues.
Status codes
| Code | Meaning | Retry? |
|---|---|---|
200 | Success | - |
400 | A coded request problem: a bad Idempotency-Key, a query string alongside it, an API key in the MCP URL, or output_schema with stream=true. See Error codes. | No (fix the request) |
401 | Missing or invalid X-API-Key. | No |
402 | A payment for your subscription failed (code: payment_required). | No (fix billing first) |
403 | No active subscription (code: no_active_subscription), or the selected mode isn't available on your plan (code: mode_not_in_plan). | No (subscribe, pick a lower mode, or upgrade) |
404 | Endpoint or resource not found. | No |
409 | An earlier call with the same Idempotency-Key is still in flight. | Yes, once it completes |
413 | Request body is larger than 8 MiB. This response has a plain-text body, not JSON. | No (send a smaller body) |
422 | The body is malformed or a field is invalid. See Validation. A structured run that hit the agent's step limit also returns 422 (code: agent_budget_exceeded) and isn't billed. | No (fix the body, or narrow the prompt or schema) |
429 | Rate limit exceeded (code: rate_limited), the period's quota is spent (code: quota_exceeded), or your plan's concurrent agent runs are all in use (code: too_many_concurrent_runs). | Yes: after Retry-After for a rate limit or concurrent runs, after X-Quota-Reset for quota |
500 | Bug on the NeuroAPI side. Report it with X-Request-Id. | Maybe (idempotent calls) |
502 | The model kept returning a response the agent couldn't use, for example output that never matched output_schema (code: agent_model_error). It isn't billed. | Yes, or simplify output_schema |
503 | Agent capacity saturated. | Yes, with backoff |
504 | A non-streaming run passed 5 minutes and was stopped (code: agent_timeout). It isn't billed. | Yes, ideally with stream=true or a simpler prompt |
Error codes
Most errors carry a machine-readable code inside detail.
code | Status | What happened | What to do |
|---|---|---|---|
invalid_idempotency_key | 400 | Idempotency-Key isn't 1-255 printable ASCII characters. | Fix the header value. |
invalid_query_string | 400 | A query string was sent alongside Idempotency-Key. | Move the parameters into the body. |
streaming_unsupported_for_structured_output | 400 | output_schema was combined with stream=true. | Set stream=false; structured output is non-streaming. |
api_key_in_query | 400 | The MCP URL's query string contains an API key, or a parameter such as api_key, key, or token. | Send the key in the X-API-Key or Authorization: Bearer header, and rotate it. |
payment_required | 402 | A payment for your subscription failed. | Update your payment method in the dashboard → Billing & Plans, then retry. |
quota_exceeded | 429 | The plan's request quota is spent. | Wait for X-Quota-Reset, or upgrade. |
mode_not_in_plan | 403 | The requested mode isn't on your plan. | Use a lower mode, or upgrade. |
no_active_subscription | 403 | The key is valid but the account has no active plan. | Subscribe, then retry. |
mcp_origin_not_allowed | 403 | A browser Origin hit the MCP endpoint from an untrusted host. | Call MCP server-side. |
idempotent_request_in_flight | 409 | An earlier call with the same Idempotency-Key is still running. | Retry once it finishes. |
idempotency_key_mismatch | 422 | The same Idempotency-Key was reused with a different body. | Use a fresh key for a different request. |
invalid_output_schema | 422 | output_schema isn't a usable JSON Schema. | Fix the schema. |
agent_budget_exceeded | 422 | A structured run hit the agent's step limit before it produced output matching output_schema. It isn't billed. | Narrow the prompt or simplify output_schema, then retry. |
rate_limited | 429 | The per-key rate limit was hit, or a per-IP limit on the MCP endpoint. | Back off for Retry-After seconds. |
too_many_concurrent_runs | 429 | Your plan's limit on agent runs in flight at once is reached (Starter 2, Pro 5, Enterprise 10). | Wait for a run to finish, then retry. |
agent_model_error | 502 | The model kept returning a response the agent couldn't use, for example output that never matched output_schema. It isn't billed. | Retry, or simplify output_schema. |
agent_timeout | 504 | A non-streaming run passed 5 minutes and was stopped. It isn't billed. | Retry, or stream the response. |
401 and 503 carry no code - branch on the status for those.
Validation (422)
Anatomy of a 422
Each entry returns the field path and an explanation. Treat the
loc array as the JSON pointer into your request body.
{
"detail": [
{
"type": "missing",
"loc": ["body", "prompt"],
"msg": "Field required"
}
]
}When to retry
Retry 503, 504, 409, and any 429 that carries Retry-After (a
rate limit or concurrent runs) with exponential backoff. A quota 429
only clears at X-Quota-Reset. Cap retries (NeuroAPI recommends
three) and surface the failure to the caller. The agent is non-idempotent:
two calls produce two answers and two charges, so don't retry blindly on
500.
Send an Idempotency-Key to remove that
caveat: with one, a retry replays the original response instead of
running and billing a second time.
Report an issue
Send NeuroAPI support:
- The
X-Request-Idfrom the failing response. - The HTTP status and body.
- The approximate timestamp (UTC).
- The mode and prompt shape. You don't need to share the full prompt content if it's sensitive, because the request ID is enough on the NeuroAPI side.