Benefit Verification Response Handling

Benefit verification responses answer three separate questions:

Did the API accept the request?
Is verification still running?
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. 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 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 for authentication, validation, and error-envelope semantics.

Getting Started