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

# Errors and Rate Limits

> Error codes, rate limits and retry guidance for the Call Export API.

## Error envelope

```json
{
  "success": false,
  "error": "Request validation failed",
  "code": "VALIDATION_ERROR",
  "details": [{ "field": "to", "message": "window must not exceed 31 days" }],
  "request_id": "4d1b0e2a-7c3f-4f1e-9b6a-2d9e8a1c5f00"
}
```

`details` is present only on validation errors. Error messages never contain call content, storage paths or internal identifiers.

## Error codes

| HTTP | `code`                    | Meaning                                                                                                                                     |
| ---- | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| 400  | `VALIDATION_ERROR`        | A parameter or body field is invalid; see `details`.                                                                                        |
| 400  | `INVALID_CURSOR`          | The cursor expired (24 h), was altered, does not belong to your key, or was sent together with other filters. Start again from `from`/`to`. |
| 401  | `AUTH_FAILED`             | Key missing, unknown or revoked.                                                                                                            |
| 401  | `KEY_EXPIRED`             | The key has an expiry date that has passed.                                                                                                 |
| 403  | `SCOPE_DENIED`            | The key does not carry the `calls:read` scope (for example a Lead Receive key).                                                             |
| 403  | `FEATURE_DISABLED`        | The Call Export API is not enabled for your company.                                                                                        |
| 404  | `NOT_FOUND`               | Recording endpoint only: no such call in your company.                                                                                      |
| 409  | `RECORDING_NOT_AVAILABLE` | The call exists but has no downloadable recording; the body carries `status` and `reason`.                                                  |
| 413  | `PAYLOAD_TOO_LARGE`       | Request body too large.                                                                                                                     |
| 416  | `RANGE_NOT_SATISFIABLE`   | Invalid `Range` header on a recording download.                                                                                             |
| 429  | `RATE_LIMITED`            | Too many requests for this key; wait `Retry-After` seconds.                                                                                 |
| 500  | `INTERNAL_ERROR`          | Unexpected error on SimZ's side.                                                                                                            |
| 503  | `DEPENDENCY_UNAVAILABLE`  | A SimZ dependency is temporarily unavailable; retry with backoff.                                                                           |

## Rate limits

Limits are applied per API key and per minute, with a sliding window:

| Endpoint                         | Limit                 |
| -------------------------------- | --------------------- |
| `GET /calls`                     | 60 requests / minute  |
| `POST /calls/retrieve`           | 30 requests / minute  |
| `GET /calls/{call_id}/recording` | 120 requests / minute |

Responses carry `X-RateLimit-Limit` and `X-RateLimit-Remaining`. A `429` response also carries `Retry-After` (seconds) and `retry_after_seconds` in the body.

## Retry guidance

* `429` → wait `Retry-After` seconds, then retry.
* `503`, `500`, network errors → exponential backoff starting at 2 seconds, at most 5 attempts.
* `400`, `401`, `403`, `404` → do not retry without changing the request.
* All endpoints are read-only; retrying never creates duplicate data. A truncated recording download can be resumed with a `Range` header.

## Caching and transport

Every response is served over TLS with `Cache-Control: no-store`. Do not cache transcripts or recordings in shared caches, and store the API key in a secret manager — never in client-side code or URLs.