Errors

The API uses standard HTTP status codes. A 2xx code means the request worked. A 4xx code means something in the request needs to change. A 5xx code means the request failed on our side.

Error body

Every error response is JSON with a detail field. Most of the time detail is a readable message:

{ "detail": "Agent not found" }

Some errors return an object in detail so your code can act on it. Always check whether detail is a string or an object before you display it.

Validation errors

When the request is missing a field or a field has the wrong type, the API returns 422 and detail is a list. Each item names the field in loc:

{
  "detail": [
    {
      "type": "missing",
      "loc": ["header", "X-API-Key"],
      "msg": "Field required",
      "input": null
    },
    {
      "type": "missing",
      "loc": ["body", "agent_id"],
      "msg": "Field required",
      "input": {}
    }
  ]
}

Feature not in your plan

When your plan does not include a feature, the API returns 403 with a code you can check:

{
  "detail": {
    "code": "feature_not_in_plan",
    "feature": "workflows",
    "message": "This feature ('workflows') is not available on your current plan."
  }
}

See voisx.ai/pricing for what each plan includes.

Rate limit exceeded

When a key goes over its limit, the API returns 429 with your current counts. See Rate limits.

{
  "detail": {
    "message": "Rate limit exceeded",
    "minute_count": 61,
    "day_count": 412,
    "minute_limit": 60,
    "day_limit": 10000
  }
}

Service temporarily unavailable

When the agent service is temporarily unavailable, the API returns 503 with a Retry-After header in seconds:

{
  "detail": "The AI agent service is temporarily unavailable. Please try again later."
}

Status codes

Code	Meaning	What to do
200	Success.
204	Success, with no response body.
400	The request was understood but cannot be done, for example a tool name the agent does not have.	Read detail, fix the request.
401	The API key is missing a permission, unknown, revoked, or not allowed from this domain.	Check the key, its permissions and its domain restriction. See Authentication.
402	Your organization has no active subscription or not enough credit.	Add credit in the console under Billing.
403	The key cannot use this agent, or your plan does not include the feature.	Check the agent restriction on the key, or your plan.
404	The agent, project or webhook was not found.	Check the ID and that you are calling the right region.
422	A field is missing or has the wrong type.	Fix the fields listed in detail.
429	Rate limit reached, or your organization is using all the concurrent sessions or runs your plan allows.	Wait and retry. Use exponential backoff.
500	Something went wrong on our side.	Retry once. If it keeps failing, contact us.
502	A third-party provider the request depends on returned an error.	Retry after a short wait.
503	A service is temporarily unavailable.	Wait for the number of seconds in Retry-After if it is set, otherwise a few seconds, then retry.
504	A workflow run took longer than your plan allows.	Shorten the workflow, or contact us.

Retrying

Retry only 429, 502, 503 and 504, and 500 at most once. Wait longer between each attempt, for example 1, 2, 4 and 8 seconds. Do not retry other 4xx codes without changing the request.

note

Starting a session or a workflow run can reserve credit. If you retry quickly after a 402 or a concurrency 429, you get the same answer until a running session or run ends.