API Limits & Statuses

Rate limiting rules and expected HTTP response status codes for all CCaaS API endpoints.

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 Practice
Schedule 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

Agent Management APIs

The Agent Management APIs differ from the table above in the following ways.

They also return these statuses:

Status	Description
`201 Created`	An agent was created
`406 Not Acceptable`	The `Accept` header excludes JSON
`409 Conflict`	The request conflicts with existing data
`413 Payload Too Large`	The request contains more than 500 agents, or its `Content-Length` is over 10 MiB
`415 Unsupported Media Type`	The request body is not `application/json`
`502 Bad Gateway`	A caller ID could not be checked with the phone system; nothing was saved

503 Service Unavailable — In addition to maintenance or an outage, a 503 from these endpoints also means another settings save held the lock. Nothing was saved, and the write can be retried at once.
429 Too Many Requests is not a rate limit — Agent writes run one at a time per tenant, and a second concurrent write is refused. Retry after a short wait, and never send writes in parallel.
No 422 — These endpoints do not use 422 Unprocessable Entity. Validation failures return 400 or 409 with a machine-readable errors[].reason.

For the full list of error reasons, see Errors on the Agent Management APIs page.

Updated 9 days ago