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

# Understanding API Responses

> How to interpret HTTP errors, response envelopes, and asynchronous workflow states.

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:

1. Did the API accept the request?
2. If it did, what is the current workflow state?
3. 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:

```json theme={null}
{
  "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](/api-reference/medication-benefit-check/response-handling)
and [Prior Authorization Response Handling](/api-reference/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](/api-reference/webhooks) 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](/api-reference/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.