Errors & rate limits

Every error response is JSON with a detail field describing what went wrong.

Status codes you might see

Status	When	What to do
`400 Bad Request`	Malformed JSON or business-rule violation	Check the `detail` message
`401 Unauthorized`	Missing or invalid `X-API-Key`	Verify the header and key value
`404 Not Found`	Session, DID, or tenant resource doesn't exist (or doesn't belong to you)	Confirm IDs and tenant scope
`409 Conflict`	Requested masked number is in use, or no free DID in your pool	Retry without `masked_e164`, or wait for capacity
`422 Unprocessable Entity`	Request body fails validation (E.164 format, missing fields)	Inspect Pydantic errors in `detail`
`429 Too Many Requests`	Rate limit exceeded for this API key	Back off and retry
`5xx`	Upstream telco or CloudTalk Networks issue	Retry with backoff; contact support if it persists

Example error body

{
  "detail": "Session not found"
}

For validation errors (422), detail is an array of field-level messages following the FastAPI convention.

Rate limits

Limit	Default value
Requests per minute, per API key	120
Window	60 seconds (rolling)

A 429 response means you've exceeded the limit. Back off; the bucket refills within 60 seconds. If you have a workload that needs higher throughput, contact us — limits are per-tenant and tunable.

Idempotency tips

Re-requesting POST /v1/sessions/{ref}/complete for an already-completed session returns success — safe to retry.
Re-requesting POST /v1/sessions with the same body creates a new session. Use your own order_id to dedupe on your side, or check GET /v1/sessions first.

Telco-side issues

When the underlying telco network is unreachable or refuses an action, you may see:

502 Bad Gateway — CloudTalk Networks reached the telco but the response was invalid
503 Service Unavailable — telco temporarily not accepting requests

Both are transient. Retry with exponential backoff (e.g. 1s, 2s, 4s, 8s).