Skip to main content

​
Errors & Rate Limits

This page describes the most common response codes and integration patterns to handle when using the NeuralVerge API.

​
Common status codes

​
400 Bad Request

The request body or parameters are invalid. Typical causes:
  • missing required fields
  • invalid JSON
  • invalid UUID, URL, email, or phone format
  • unsupported option values

​
401 Unauthorized

Authentication failed. Typical causes:
  • missing Authorization header
  • invalid bearer token format
  • expired or invalid token

​
402 Payment Required

The operation cannot proceed because of plan or usage limits. Typical causes:
  • points limit exceeded
  • inactive subscription
  • expired subscription

​
404 Not Found

The requested resource does not exist or is not available to the current user. Typical causes:
  • invalid session_id
  • missing agent
  • inaccessible resource

​
429 Too Many Requests

The request was queued but could not be started within the queue timeout. Typical causes:
  • your organization’s requests-per-second limit is saturated
  • your organization’s concurrent request limit is saturated
  • a specific endpoint’s own per-function rate limit is saturated
See Rate limits below for how this works and how to avoid it.

​
500 Internal Error

An internal processing error occurred. Typical causes:
  • upstream provider issues
  • temporary service failure
  • unexpected backend processing error

​
Rate limits

Rate limits apply per organization — they’re shared across every API key and user in your organization, not tracked per key. Instead of rejecting a request the instant a limit is hit, NeuralVerge queues it (oldest request first, per endpoint) and starts it as soon as capacity frees up. A request only fails with 429 Too Many Requests if it’s still waiting after 60 seconds in the queue. Under normal load this queueing is invisible — it just means an occasional call takes a little longer to start, not that it fails. Three limits are enforced together, checked in this order: Higher organization-wide limits can be configured on your account — reach out if your integration needs sustained throughput above the defaults.

​
Handling 429

  • Back off and retry — the queue timeout means the request never ran, so it’s always safe to retry
  • Use exponential backoff rather than retrying immediately in a tight loop
  • If you’re regularly hitting the queue timeout, spread requests out over time instead of bursting them

​
Polling asynchronous jobs

For async endpoints:
  1. Call the run endpoint
  2. Save the returned session_id
  3. Poll Get Session Status
  4. Stop polling when the status becomes complete or failed
A practical polling strategy is:
  • poll every 2 to 5 seconds
  • set a reasonable overall timeout
  • log the last known status
  • handle temporary failures gracefully

​
Retry guidance

Retries are useful for:
  • temporary network errors
  • intermittent 500 responses
  • short-lived upstream issues
  • 429 responses, after a backoff — see Handling 429
Retries usually do not help for:
  • 400
  • 401
  • 402
  • 404

​
Example error

The exact error payload can vary by endpoint.