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

# Benefit Verification Response Handling

> How to interpret request errors, workflow states, and benefit verification failures.

Benefit verification responses answer three separate questions:

1. Did the API accept the request?
2. Is verification still running?
3. If it stopped, did it produce a coverage result or a workflow error?

## Choose the right signal

| Situation                      | Source of truth                          | Meaning                                                                          |
| ------------------------------ | ---------------------------------------- | -------------------------------------------------------------------------------- |
| The create request is rejected | HTTP status and top-level `error.code`   | The API did not return a newly accepted benefit verification ID.                 |
| The create request succeeds    | Returned `data.id`                       | Store the ID and begin monitoring the resource.                                  |
| Verification is running        | `data.status: "pending"`                 | Continue waiting. Result fields may still be `null` or `unknown`.                |
| Verification completes         | `data.status: "completed"`               | Read the coverage result fields. This is not an error.                           |
| Verification fails             | `data.status: "failed"` and `data.error` | Use the workflow error code to correct, replace, or manually handle the request. |

## Lifecycle

| `data.status` | Terminal | Meaning                                                                         |
| ------------- | -------- | ------------------------------------------------------------------------------- |
| `pending`     | No       | The request is queued or verification is in progress.                           |
| `completed`   | Yes      | Verification finished. Read `patient_coverage_status` and each item in `drugs`. |
| `failed`      | Yes      | The workflow could not complete. Inspect `data.error`.                          |
| `cancelled`   | Yes      | The request was cancelled and no further verification work will be created.     |

The normal transitions are `pending` to `completed`, `failed`, or `cancelled`.
Develop Health can retry a failed verification internally. When that happens,
the resource moves from `failed` back to `pending`; consumers should accept this
transition instead of enforcing terminal states as permanently immutable.

`data.status_description` is display text. Do not branch on it because its
wording can change without a versioned API change.

### Coverage results are not errors

After `completed`, use `patient_coverage_status` and `drugs` for the business
result. Clients should tolerate new result enum values rather than converting an
unfamiliar coverage result into a failed workflow.

## Request errors

These codes can be returned by
[Run Benefit Verification](/api-reference/medication-benefit-check/post). Branch
on `error.code`, not the human-readable title or description.

| HTTP status | `error.code`                           | Meaning                                                                  | Recommended handling                                                                                               |
| ----------- | -------------------------------------- | ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------ |
| `400`       | `invalid_us_state`                     | `patient.address.state_province` is not a valid US state.                | Correct the state and resubmit.                                                                                    |
| `400`       | `mock_result_not_allowed`              | A production organization sent `mock_result` or another mock-only field. | Remove mock-only fields and resubmit.                                                                              |
| `400`       | `unknown_ndc`                          | A supplied NDC could not be resolved to a valid drug.                    | Correct the NDC or use the appropriate manual process.                                                             |
| `400`       | `referenced_resource_not_found`        | The benefit verification named by `replaces` does not exist.             | Verify the replacement ID and resubmit.                                                                            |
| `409`       | `referenced_resource_invalid_conflict` | The benefit verification named by `replaces` has not been cancelled.     | Continue using the existing verification or cancel it before creating a replacement.                               |
| `500`       | `unexpected_error`                     | An unexpected internal error occurred.                                   | Use a manual fallback and contact support. Retry only if the integration can safely reconcile a duplicate request. |

### Insurance-document errors

Insurance-document processing can also return these `400` codes:

| `error.code`            | Meaning                                                     | Recommended handling                              |
| ----------------------- | ----------------------------------------------------------- | ------------------------------------------------- |
| `conversion_exception`  | A document could not be converted into the required format. | Replace or re-export the document, then resubmit. |
| `decode_exception`      | The supplied Base64 data could not be decoded.              | Correct the encoding and resubmit.                |
| `unsupported_mimetype`  | The detected document type is not supported.                | Convert the document to a supported type.         |
| `multipage_pdf`         | An insurance-card PDF contains more than one page.          | Upload a single-page PDF or image.                |
| `corrupted_pdf`         | The PDF appears corrupted or incomplete.                    | Upload a valid copy of the document.              |
| `unsupported_file_type` | A file uses an unsupported format.                          | Convert the file to a supported type.             |

## Workflow failures

A successful create response does not rule out a later workflow failure.
Problems such as unreadable insurance information or a payer that cannot locate
the patient appear on the accepted resource returned by
[Retrieve Benefit Verification](/api-reference/medication-benefit-check/get_item)
and its webhook.

When `data.status` is `failed`, `data.error` can contain a stable `code` and
`detail_code` alongside human-readable fields. A code can be `null` on legacy
verifications; handle it like `Internal Error`.

### Error codes

These values are case-sensitive.

| `data.error.code`                         | Meaning                                                                        | Recommended handling                                                                             |
| ----------------------------------------- | ------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------ |
| `Patient Not Found`                       | The plan contact could not locate the patient.                                 | Verify the member ID, name, date of birth, and insurance documents before replacing the request. |
| `Insurance Card OCR Failure`              | Required information could not be read from the insurance card.                | Upload clearer card images or provide the insurance values as structured data.                   |
| `Insurance Unable to Provide Information` | The payer or PBM would not or could not provide the needed information.        | Review the message and use a manual process if the request is urgent.                            |
| `Document Quality Error`                  | An uploaded document was blurry, low resolution, or otherwise unusable.        | Upload a higher-quality document.                                                                |
| `Document Info Missing or Incorrect`      | Required patient or insurance information was missing, outdated, or incorrect. | Use `detail_code` to correct the request, then replace it.                                       |
| `Unable to Route Call`                    | The system could not determine a valid payer or PBM contact number.            | Provide additional insurance, payer, or plan information.                                        |
| `Unable to Gather Benefits`               | Benefits could not be gathered after the available attempts.                   | Review the request data and use a manual fallback when needed.                                   |
| `Internal Error`                          | An internal workflow error prevented completion.                               | Use a manual fallback for urgent work and contact support with the benefit verification ID.      |
| `Provider Not Authorized`                 | The NPI cannot be used for this verification.                                  | Complete provider authorization or review `detail_code` for a network-specific restriction.      |
| `Patient Consent Required`                | The payer requires the patient to provide verbal consent.                      | Obtain the required consent, then submit a replacement benefit verification.                     |

### Detail codes

| `data.error.detail_code`     | Meaning                                                                                                 |
| ---------------------------- | ------------------------------------------------------------------------------------------------------- |
| `incorrect_member_id`        | The member ID is incorrect.                                                                             |
| `incorrect_dob`              | The patient's date of birth is incorrect.                                                               |
| `incorrect_address`          | The patient's address is incorrect.                                                                     |
| `incorrect_phone_number`     | The patient's phone number is incorrect.                                                                |
| `missing_member_id`          | The member ID is missing.                                                                               |
| `medical_only_member_id`     | The supplied member ID covers medical benefits only.                                                    |
| `name_mismatch`              | The patient's name does not match the insurance card.                                                   |
| `missing_tax_id`             | The provider or entity tax ID is missing.                                                               |
| `incorrect_tax_id`           | The provider or entity tax ID is incorrect.                                                             |
| `incorrect_npi`              | The provider NPI is incorrect.                                                                          |
| `patient_consent_required`   | The payer requires the patient to provide verbal consent.                                               |
| `patient_declined_consent`   | The patient declined to provide the required consent.                                                   |
| `kaiser_prescriber_required` | Kaiser requires prescribing, benefits, and prior authorization work to be handled by a Kaiser provider. |
| `expired`                    | The benefit verification expired under the account's configured expiry rules.                           |

## Retrieve errors

| HTTP status | Code or response                                        | Meaning                                                                            |
| ----------- | ------------------------------------------------------- | ---------------------------------------------------------------------------------- |
| `404`       | `{"detail":"No benefit verification found for id ..."}` | No benefit verification with that ID is visible to the authenticated organization. |
| `400`       | `benefit_verification_serialization_error`              | The stored benefit verification could not be serialized into the public response.  |

## Monitoring and unknown values

Use the retrieve endpoint to poll the current resource. The
`benefit_verification.status_change` webhook delivers the full resource when
verification completes or fails. Process webhooks idempotently and retrieve the
resource when you need to reconcile its current state.

Treat code lists as extensible. Preserve unknown values in logs and use the same
manual fallback as the closest catch-all error instead of failing to parse the
response. See [Understanding API Responses](/api-reference/response-handling)
for authentication, validation, and error-envelope semantics.