NeuroAPIGuidesErrors
Errors
Status codes, error format, and when to retry.
The public API uses standard HTTP status codes. Error bodies have a single shape:
{
"detail": "Human-readable message"
}Every error response also carries an X-Request-Id header. Quote it
when reporting issues.
Status codes
| Code | Meaning | Retry? |
|---|---|---|
200 | Success | - |
400 | Malformed body or invalid field. Don't retry without fixing. | No |
401 | Missing or invalid X-API-Key. | No |
402 | No active subscription, or quota exhausted. | No (fix billing first) |
403 | Selected mode isn't available on your plan (code: mode_not_in_plan). | No (pick a lower mode or upgrade) |
404 | Endpoint or resource not found. | No |
422 | Validation error on the request body. | No |
429 | Rate limit exceeded. Honour Retry-After. | Yes, after Retry-After |
500 | Bug on our side. Please report with X-Request-Id. | Maybe (idempotent calls) |
503 | Agent capacity saturated. | Yes, with backoff |
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 429 and 503 with exponential backoff. Cap retries (we
recommend three) and surface the failure to the caller; the agent is
non-idempotent in the sense that two calls produce two answers and two
charges, so don't retry blindly on 500.
Report an issue
Send us:
- The
X-Request-Idfrom the failing response. - The HTTP status and body.
- The approximate timestamp (UTC).
- The mode and prompt shape (no need to share the full prompt content if it's sensitive - the request id is enough on our side).