API Limits & Statuses
This page applies to all CCaaS API endpoints documented under Data APIs and Action APIs.
Request Frequency Limit
Recording audio requests must not exceed one request per 3 seconds per tenant. Exceeding this limit returns a 429 Too Many Requests response.
Best PracticeSchedule recording pulls to run nightly. Sending GET requests for recordings no more frequently than once every 3 seconds per tenant keeps well within the limit.
Multiple tenants may be queried simultaneously — the limit is scoped per tenant, not across tenants.
Rolling Egress Limit
A 5-day rolling egress cap is enforced per tenant, calculated based on the number of licensed recorded agents. The cap is set to approximately double the expected GB volume for agents recording full 8-hour shifts.
If the cap is reached, requests return 509 Bandwidth Limit Exceeded. Contact Xima Support to review usage and request a reset if the limit was reached due to a bug or unintended behavior.
Expected Response Statuses
| Status | Method(s) | Description |
|---|---|---|
200 OK | GET, POST | Request executed successfully; returns appropriate response data |
202 Accepted | POST | The Historical Call Data report request timed out before completing; the report has been cached and will be available on retry with the same parameters |
204 No Content | POST | Request executed successfully; no response body is returned (Click to Dial and Callback API) |
400 Bad Request | GET, POST | The request is malformed or contains missing/invalid parameters; check query parameters (GET) or the request body structure and field values (POST) |
401 Unauthorized | GET, POST | The bearer token is missing, expired, or invalid; verify the Authorization header is correctly formatted and the token is active |
403 Forbidden | GET, POST | The token is valid but does not have permission to access the requested resource; verify the Service User has the appropriate role and access |
404 Not Found | GET, POST | The specified resource does not exist; check that the report_id, recording_key, or other path parameters are correct and belong to the authenticated tenant |
405 Method Not Allowed | GET, POST | The HTTP method used is not supported by the endpoint; verify the correct method (GET vs. POST) for the target endpoint |
422 Unprocessable Entity | POST | The request body is structurally valid JSON but contains semantically incorrect values (e.g., unrecognized parameter names, invalid date formats, or unsupported format values) |
429 Too Many Requests | GET, POST | The request rate limit has been exceeded; reduce request frequency and implement retry logic with exponential backoff |
500 Internal Server Error | GET, POST | An unexpected error occurred on the server; the request may be retried, but if the issue persists it should be reported to Xima support |
503 Service Unavailable | GET, POST | The service is temporarily unavailable, typically due to maintenance or an outage; retry the request after a brief delay |
509 Bandwidth Limit Exceeded | GET | The 5-day rolling recording egress cap for the tenant has been reached; contact Xima Support to review usage and request a reset |