Async jobs
Some endpoints return queued or asynchronous responses. The docs must describe those as accepted work, not completed workflow execution.
No universal job contract yet
Until a shared job schema and status endpoint are declared, each endpoint page should document only the operation-specific behavior visible in OpenAPI and release evidence.
Current rules
| Topic | Guidance |
|---|---|
| Current evidence | 68 generated operations include HTTP 202. |
| Shared job schema | Not yet declared in OpenAPI. Use only operation-specific status endpoints. |
| Queueing | A queued response means work was accepted or scheduled; it is not completion. |
| Polling | Use endpoint-specific polling guidance where available. Generic polling intervals are not public contract yet. |
| Retries | Retry only after checking resource, job, or batch state. Do not assume universal idempotency. |
| Results | Retention, cancellation, result files, and terminal states are unresolved unless stated on the endpoint page. |
Lifecycle vocabulary
| State | Meaning | Public guidance |
|---|---|---|
| Accepted | The request passed initial checks and work was accepted, queued, or scheduled. | Return handling should store the returned resource, job, batch, or correlation ID if the endpoint provides one. |
| In progress | Processing may be local, queued, worker-based, or dependent on an external system. | Poll only documented status endpoints. Do not infer progress from elapsed time or repeated 202 responses. |
| Terminal success | The endpoint-specific workflow reached a completed or available state. | Use only the endpoint's documented success state names and result fields. |
| Terminal failure | Validation, ownership, vendor, file, timeout, quota, or workflow state prevented completion. | Display sanitized failure text only. Do not expose raw payer, EHR, worker, LLM, OCR, or EDI payloads. |
| Canceled or expired | Cancellation, expiration, and retention are not universal public contracts yet. | Document only when an endpoint declares the behavior and release evidence proves it. |
Claims that need review
| Claim | Status |
|---|---|
| A 202 response means the job finished. | Not approved. 202 means accepted, queued, or scheduled unless an endpoint says otherwise. |
| All async endpoints can be polled the same way. | Not approved. No shared job schema or universal status endpoint is declared. |
| Clients can safely retry the same POST after timeout. | Needs endpoint-specific idempotency review. |
| Result files can be downloaded from the job response. | Needs file/artifact policy and endpoint-specific result retention approval. |