> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.formantai.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.formantai.com/_mcp/server.

# Errors & Rate Limits

> Handle API errors, rate limits, idempotency, and concurrency limits.

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

## Error format

```json
{
  "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.                          |
| `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.                                           |

## Rate limit headers

Every API response may include rate limit headers:

```http
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:

```http
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`.

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

## Concurrency limits

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

```json
{
  "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.