Understanding API Responses

Develop Health APIs report whether a request was accepted separately from what happens in the workflow it creates. Integrations should answer these questions in order:

Did the API accept the request?
If it did, what is the current workflow state?
If the workflow stopped, which code explains what the caller should do next?

Read each response at the appropriate layer:

Layer	Field	Meaning
HTTP	HTTP status code	Whether the API accepted and handled this HTTP request.
Envelope	Top-level `status`	Whether this API response is a `success` or `error`.
Workflow	`data.status`	The current state of an asynchronous resource, such as a benefit verification or prior authorization.
Result	Product-specific fields in `data`	The final coverage, outcome, or failure details.

An envelope status of success means the HTTP request succeeded. It does not mean an asynchronous workflow has completed.

Which signal to handle

Situation	Source of truth	What to do
A create request is rejected	HTTP status and top-level `error.code`	No newly accepted workflow ID was returned. Correct the request, use an existing workflow identified by the error, retry, or fall back.
A create request is accepted	`data.id`	Store the resource ID and monitor it by webhook or the retrieve endpoint.
A workflow is in progress	`data.status`	Continue waiting. Do not infer completion from a placeholder result field.
A benefit verification fails	`data.status: "failed"` and `data.error`	Branch on `data.error.code` and, when present, `detail_code`.
A PA stops before submission	`data.status: "not_submitted"` and `data.outcome.detail_code`	Treat the PA as terminal and decide whether to correct, resubmit, or use another submission path.
A PA completes with an exceptional result	`data.status: "completed"`, `data.outcome.result: "Other"`, and `detail_code`	Treat the PA as terminal. The detail code explains why it did not end in approval or denial.
A nested operation fails	The nested object’s `status` and error fields	Handle the nested operation independently from the parent PA state.

Approved, Denied, and benefit coverage results are business outcomes, not API or workflow errors.

API errors

An API error means the request did not return a newly accepted workflow ID. Do not start monitoring a new resource unless the error identifies an existing workflow to use. The create endpoint pages list the public codes and recommended caller action.

Error response formats

Business errors generally use a structured envelope:

{
  "status": "error",
  "error": {
    "title": "Unsupported Drug",
    "code": "unsupported_drug",
    "description": "The drug you submitted is not yet supported."
  },
  "data": null
}

Branch on error.code, not the human-readable title or description. Treat unknown future codes as recoverable unknown values and preserve them in logs. Request parsing, validation, and some not-found errors use a standard detail response instead. Validation responses contain a detail array whose loc field identifies the invalid request field.

HTTP status	Meaning
`401`	The JWT is missing, invalid, expired, or does not identify a valid organization.
`422`	The path parameters or request body failed schema validation.

Endpoint pages list their additional error codes and status codes.

Workflow errors and exceptional outcomes

Workflow errors happen after a create request was accepted, so they are exposed on the resource returned by a retrieve endpoint or webhook rather than as the original create response. The exact signal is product-specific:

Benefit verifications use data.status: "failed" with data.error.code and an optional detail_code.
Prior authorizations distinguish not_submitted, failed, and a completed Other outcome. These signals have different meanings and should not be collapsed into a single generic failure.
Nested work such as prescription transfer has its own state and error fields; it does not change the meaning of the parent PA’s status.

Use the endpoint-specific code tables for caller behavior. Treat code enums as extensible: preserve an unknown value in logs and route it through the same manual fallback as the product’s catch-all code instead of failing to parse the response. For the complete product contracts, see Benefit Verification Response Handling and Prior Authorization Response Handling.

Monitoring asynchronous workflows

After creating a benefit verification or prior authorization, use the retrieve endpoint or subscribe to the relevant webhook until data.status is terminal. Use the workflow state as the source of truth for progress, even when a nested result field contains a placeholder such as Pending. For resource-state webhook events, data uses the response schema from the corresponding retrieve endpoint. Provider outreach events use a dedicated payload; see Provider outreach webhooks. Process notifications idempotently because a delivery can be retried, and use the retrieve endpoint to reconcile the current resource state when needed. A PA webhook can describe an intermediate state or a nested update; it does not necessarily mean the PA is terminal.

Getting Started

Benefit Verification

Prior Authorization

Prior Authorization Status (Coming Soon)

Understanding API Responses

Which signal to handle

API errors

Error response formats

Workflow errors and exceptional outcomes

Monitoring asynchronous workflows

​Which signal to handle

​API errors

​Error response formats

​Workflow errors and exceptional outcomes

​Monitoring asynchronous workflows

Which signal to handle

API errors

Error response formats

Workflow errors and exceptional outcomes

Monitoring asynchronous workflows