Lifecycle, limits and troubleshooting

Three different identifiers

Identifier	Used for
`requestId`	Optional caller-chosen retry key, 1–64 ASCII letters, digits, underscores or hyphens
`runId`	Server-returned 64-character hex identifier used for status and cancel
`recordingCallId`	SIP recording-session correlation for Support; not the backend call ID

Receipt ownership is tenant-scoped. A refreshed token or another authorized key for the same tenant can access its receipts. Other tenants receive 404, not another tenant’s call details.

Receipts and replay

A receipt is stored progress for one intentional test. Sending the same retained requestId with the same normalized body returns that receipt without another call. The original createdAt does not change, including after a service deployment. A completed replay can return 202. If a call appears to finish immediately, compare runId and createdAt with your previous test. Omit requestId for each manual new test, or generate a new ID. For retryable automation, generate one ID before the first POST and reuse it with the same payload on every retry of that call. If a request without an ID times out, its generated ID may not have reached you; blindly resending can be a new call. Use explicit stable IDs where duplicate prevention matters. Receipts normally expire after 24 hours, but older terminal receipts can be evicted under history capacity pressure. Retention is not permanent duplicate protection: an expired/evicted ID can be treated as a new request. Active and uncertain work is not evicted just to admit another call. Once a receipt is gone, status returns 404.

Recording states

State	Interpretation
`Dispatching`	Admission is in progress; no confirmed start yet
`Accepted` / `Running`	Simulator reports accepted/active recording
`Completed`	Simulator confirmed recording termination; not proof of Assist/backend delivery
`Cancelled`	Simulator confirmed cancellation/cleanup
`Failed`	A definitive failure was recorded; inspect `error`
`Unknown`	Start or cleanup cannot be confirmed; admission may remain reserved

Startcall returns an error for uncertain/failed/cancelled admission. GET and cancel return 200 for an already-terminal receipt, including Failed or Cancelled; inspect state, not just HTTP success. A nonterminal refresh can temporarily return 503 while failure is being published.

Limits and pauses

Environment and tenant administrators can lower traffic/duration limits or pause new admissions. Limits are not negotiated by request fields. Call duration, request budgets and concurrency are controlled by the effective environment and tenant policies; ask your administrator for the current limits rather than assuming identical limits across environments. The schema describes the API’s hard ceiling, not the currently permitted duration. Only one unresolved call per tenant/station is allowed, so use different configured test stations for parallel calls. Do not use a station that carries live traffic. Custom generated audio still has a separate five-minute cap. Start, token exchange, status and cancel have bounded request budgets. Replays also consume request budget; do not poll aggressively. Honor Retry-After when present and back off with jitter. Not every 429 includes a body or retry header.

Troubleshooting

Result	What to do
`401`	Use the Coach key only for token exchange; use `access_token` for call operations. Check environment and token expiry. Authentication failures may have an empty body.
`403 test_calls_forbidden`	Ask an administrator for tenant-wide Invoke Test Calls permission; agency-restricted keys cannot use this API.
`403 tenant_forbidden`	For startcall, status or cancel, use an access token from the correct environment and tenant. Do not reuse another tenant’s run ID or request identity; ask Support to check tenant routing if the token is correct.
`400 invalid_request`	Check types, whitespace, bounds, unknown JSON fields and mutually exclusive location inputs.
`400 invalid_custom_scenario`	Check `needAudio=true`, no bundled `scenario`, roles, text, invisible pasted characters and installed language codes.
`400 location_not_configured`	Ask Support to configure location delivery before sending coordinates.
`400 invalid_location_scenario`	Check record count, ASCII station/address fields and whether the minimum send schedule fits before the maximum call end.
`400 call_length_limit`	The requested maximum exceeds the effective policy; reduce it.
`409 request_id_conflict`	Reuse the original exact body for a retry, or use a new ID for an intentional new call.
`409 run_busy`	Another operation holds the run lock; retry the same operation after a short delay.
`413` / `415`	Keep the complete body within 8 KiB and send `Content-Type: application/json` for startcall. The endpoint’s 413 uses JSON `code: request_too_large`; a server-generated 413 can instead have an empty body.
`422 recording_rejected`	Recording admission was definitively rejected; ask Support to inspect the request and destination response.
`422 custom_scenario_too_long`	Reduce generated speech/pauses below the five-minute preparation cap.
`429 station_busy` / `target_busy` / `global_calls_busy`	Existing active or unresolved work holds admission. Status/cancel that run; do not bypass it with another ID.
`429 calls_paused`	An administrator paused new calls.
Other `429`	Request or storage/admission capacity is exhausted; back off. Request codes include tenant/global start-rate limits and tenant/global receipt capacity.
`503 simulator_not_configured` / `simulator_unavailable`	Ask Support to inspect deployment and recording-server availability.
`503 simulation_uncertain` / `cleanup_uncertain`	Save the run ID. Poll/cancel safely and contact Support if it remains unresolved; it does not prove that no recording exists.
`503 audio_generation_failed`	Speech synthesis or language discovery is unavailable; contact Support.
`503 dependency_unavailable` / `admission_index_rebuilding`	New work cannot safely proceed; retry with the same ID after recovery.
`404 run_not_found`	Check the run ID, tenant and environment. The receipt may have expired or been evicted.

Token exchange has three error shapes:

Endpoint validation/authentication errors (400, 401, 403) use { "error": "..." }.
Dependency middleware failures (503) use { "code": "dependency_unavailable" }, without an error field or run ID.
Token rate-limit failures (429) have an empty body. Honor Retry-After when supplied.

Call errors normally use { "code": "...", "runId": "..." }, with a null or omitted run ID before admission. Other authentication/rate-limit middleware rejections can also have an empty body. Check the HTTP status and content before decoding JSON; do not assume one error envelope for every token response. Keep credentials out of logs and Support messages.

Completed but no call in Assist?

First exclude a retained replay by checking the receipt’s createdAt and runId. For a genuinely new run, ask Support to trace the recording ID through SIPREC → the intended SIPY subscriber → the configured Assist position → backend delivery. Verify tenant routing, position matching, ANI, audio and downstream integration results separately. Do not treat a 202, SIP acceptance, TCP write or simulator Completed result as proof of end-to-end delivery.

CAD integration

CAD API reference

Testing

Three different identifiers

Receipts and replay

Recording states

Limits and pauses

Troubleshooting

Completed but no call in Assist?

​Three different identifiers

​Receipts and replay

​Recording states

​Limits and pauses

​Troubleshooting

​Completed but no call in Assist?

Three different identifiers

Receipts and replay

Recording states

Limits and pauses

Troubleshooting

Completed but no call in Assist?