Skip to navigation

Errors and Rate Limits

View as Markdown

Error envelope

{
"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

HTTPcodeMeaning
400VALIDATION_ERRORA parameter or body field is invalid; see details.
400INVALID_CURSORThe cursor expired (24 h), was altered, does not belong to your key, or was sent together with other filters. Start again from from/to.
401AUTH_FAILEDKey missing, unknown or revoked.
401KEY_EXPIREDThe key has an expiry date that has passed.
403SCOPE_DENIEDThe key does not carry the calls:read scope (for example a Lead Receive key).
403FEATURE_DISABLEDThe Call Export API is not enabled for your company.
404NOT_FOUNDRecording endpoint only: no such call in your company.
409RECORDING_NOT_AVAILABLEThe call exists but has no downloadable recording; the body carries status and reason.
413PAYLOAD_TOO_LARGERequest body too large.
416RANGE_NOT_SATISFIABLEInvalid Range header on a recording download.
429RATE_LIMITEDToo many requests for this key; wait Retry-After seconds.
500INTERNAL_ERRORUnexpected error on SimZ’s side.
503DEPENDENCY_UNAVAILABLEA SimZ dependency is temporarily unavailable; retry with backoff.

Rate limits

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

EndpointLimit
GET /calls60 requests / minute
POST /calls/retrieve30 requests / minute
GET /calls/{call_id}/recording120 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.