Errors
NeuroAPI uses conventional HTTP status codes and a predictable JSON envelope.
Error envelope
json
{ "success": false, "error": { "code": "insufficient_credits", "message": "Account balance (12) is lower than request cost (50)." }}Status codes
| Status | Code | Meaning |
|---|---|---|
| 400 | bad_request | Invalid JSON body or missing required parameter. |
| 401 | unauthorized | Missing, malformed or revoked API key. |
| 402 | insufficient_credits | Account balance is below the cost of the request. |
| 402 | monthly_cap_exceeded | Plan-level monthly credit cap reached. Upgrade or wait for the next billing period. |
| 403 | forbidden | Authenticated, but not allowed to act on this resource (e.g. interact session you don't own). |
| 403 | forbidden_scope | API key is missing the required scope for this endpoint. |
| 403 | ip_not_allowed | Request IP is outside the key's IP allowlist. |
| 403 | robots_disallowed | Target URL is blocked by its robots.txt for our user agent. |
| 404 | not_found | Resource (e.g. job id) does not exist or doesn't belong to you. |
| 410 | session_expired | Interact session no longer exists. Call /api/v1/scrape again to get a fresh sessionId. |
| 413 | file_too_large | Upload exceeds the parse endpoint's file-size limit. |
| 415 | unsupported_media_type | Uploaded file type is not supported by /api/v1/parse. |
| 429 | rate_limited | Too many requests in a short window — back off and retry. |
| 429 | concurrency_limit_exceeded | Too many in-flight requests for this account's plan. Lower parallelism or upgrade. |
| 503 | upstream_busy | Every upstream worker is saturated; retry shortly. |
| 500 | internal_error | Unexpected server-side failure. Safe to retry idempotent calls. |
Retry strategy
Retry 429, 503 and 500 with exponential backoff (e.g. 1s, 2s, 4s, 8s) plus jitter. Do not retry 400, 401 or 402 — fix the request, fix the key, or top up credits.