> ## Documentation Index
> Fetch the complete documentation index at: https://developers.govworx.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Lifecycle, limits and troubleshooting

> Understand receipts, safe retries, cancellation and simulator outcomes.

## 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.