NeuroAPI
GuidesErrors

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

CodeMeaningRetry?
200Success-
400A 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)
401Missing or invalid X-API-Key.No
402A payment for your subscription failed (code: payment_required).No (fix billing first)
403No 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)
404Endpoint or resource not found.No
409An earlier call with the same Idempotency-Key is still in flight.Yes, once it completes
413Request body is larger than 8 MiB. This response has a plain-text body, not JSON.No (send a smaller body)
422The 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)
429Rate 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
500Bug on the NeuroAPI side. Report it with X-Request-Id.Maybe (idempotent calls)
502The 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
503Agent capacity saturated.Yes, with backoff
504A 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.

codeStatusWhat happenedWhat to do
invalid_idempotency_key400Idempotency-Key isn't 1-255 printable ASCII characters.Fix the header value.
invalid_query_string400A query string was sent alongside Idempotency-Key.Move the parameters into the body.
streaming_unsupported_for_structured_output400output_schema was combined with stream=true.Set stream=false; structured output is non-streaming.
api_key_in_query400The 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_required402A payment for your subscription failed.Update your payment method in the dashboard → Billing & Plans, then retry.
quota_exceeded429The plan's request quota is spent.Wait for X-Quota-Reset, or upgrade.
mode_not_in_plan403The requested mode isn't on your plan.Use a lower mode, or upgrade.
no_active_subscription403The key is valid but the account has no active plan.Subscribe, then retry.
mcp_origin_not_allowed403A browser Origin hit the MCP endpoint from an untrusted host.Call MCP server-side.
idempotent_request_in_flight409An earlier call with the same Idempotency-Key is still running.Retry once it finishes.
idempotency_key_mismatch422The same Idempotency-Key was reused with a different body.Use a fresh key for a different request.
invalid_output_schema422output_schema isn't a usable JSON Schema.Fix the schema.
agent_budget_exceeded422A 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_limited429The per-key rate limit was hit, or a per-IP limit on the MCP endpoint.Back off for Retry-After seconds.
too_many_concurrent_runs429Your 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_error502The 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_timeout504A 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:

  1. The X-Request-Id from the failing response.
  2. The HTTP status and body.
  3. The approximate timestamp (UTC).
  4. 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.

On this page