Response format and errors

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 through webhooks or a GET request.
A workflow is in progress	`data.status`	Continue waiting. Do not infer completion from a placeholder result field.
A workflow stops	Product-specific result and error fields	Use the product’s status and error reference to interpret the outcome and choose the next action.

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

API errors

A rejected create request does not return a newly accepted workflow ID. Do not start monitoring a new resource unless the error identifies an existing workflow to use. The product references list public codes and recommended caller actions.

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. Read the resource’s state and result from data in its GET response or webhook. Each product defines its own states, outcomes, and error fields:

Treat code enums as extensible: preserve unknown values in logs and use the product’s fallback handling instead of failing to parse the response. A business outcome such as a denial is different from a failure to process the workflow.

Monitoring asynchronous workflows

After creating a benefit verification or prior authorization, poll GET /benefit-verification/{id} or GET /prior-authorization/{id}, or subscribe to the relevant webhook. Track data.status until it is terminal. Use this status to determine progress, even when a nested result field contains a placeholder such as Pending. For BV and PA status webhooks, data uses the same schema as data in the GET responses above. Provider outreach events use a dedicated payload; see Provider outreach webhooks. Process notifications idempotently because a delivery can be retried. Call the same GET endpoint again when you need to confirm the current BV or PA status. A PA webhook can describe an intermediate state or a nested update; it does not necessarily mean the PA is terminal.

API basics

Benefit verification

Prior authorization

Prior authorization status (coming soon)

Response format and errors

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