Errors & Rate Limits

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

Error format

1
{
2
  "error": {
3
    "message": "customer_phone parameter is required",
4
    "type": "invalid_request"
5
  }
6
}

Error types

Rate limit headers

Every API response may include rate limit headers:

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

When rate limited, the response can include:

1
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.

1
{
2
  "error": {
3
    "message": "idempotency key already used",
4
    "type": "duplicate_request"
5
  }
6
}

Concurrency limits

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

1
{
2
  "error": {
3
    "message": "concurrent call limit reached. 10 simultaneous calls allowed.",
4
    "type": "concurrent_call_limit_exceeded",
5
    "current_calls": 10,
6
    "max_calls": 10
7
  }
8
}

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.