Errors & Rate Limits | FormantAI

FormantAI Voice uses conventional HTTP status codes and a consistent error body.

Error format

{
  "error": {
    "message": "customer_phone parameter is required",
    "type": "invalid_request"
  }
}

Error types

HTTP	Type	Meaning
`400`	`invalid_request`	Missing field, invalid value, bad input, or invalid schedule time.
`401`	`authentication_error`	API key is missing, invalid, or disabled.
`402`	`insufficient_credits`	The workspace balance cannot cover a billed operation (podcast, text to speech, decision generation).
`404`	`not_found`	Resource does not exist or belongs to a different tenant.
`409`	`duplicate_request`	Idempotency key was already used.
`429`	`rate_limit_exceeded`	API rate limit or per-number rate limit exceeded.
`429`	`concurrent_call_limit_exceeded`	Workspace concurrent call limit reached.
`500`	`internal_error`	Unexpected server error.
`502`	`upstream_error`	A model or prompt provider failed to produce an answer. Safe to retry with backoff.
`503`	`not_configured`	The feature is not set up on this deployment. Contact support.

Rate limit headers

Every API response may include rate limit headers:

X-RateLimit-Limit: 50
X-RateLimit-Remaining: 48
X-RateLimit-Reset: 2026-03-18T20:54:00+00:00

When rate limited, the response can include:

Retry-After: 60

Idempotency

Use idempotency_key on POST /v1/call to prevent duplicate call submissions. Reusing the same key for the same tenant and agent within 24 hours returns 409 duplicate_request.

{
  "error": {
    "message": "idempotency key already used",
    "type": "duplicate_request"
  }
}

Concurrency limits

If your workspace has reached its active call limit, POST /v1/call returns:

{
  "error": {
    "message": "concurrent call limit reached. 10 simultaneous calls allowed.",
    "type": "concurrent_call_limit_exceeded",
    "current_calls": 10,
    "max_calls": 10
  }
}

Retry strategy for API clients

Retry 429 only after Retry-After or X-RateLimit-Reset.
Retry 500 with exponential backoff.
Do not retry 400, 401, or 404 until the request is fixed.
Use idempotency keys for call creation retries.