Prior Authorization Response Handling

Prior authorization responses answer four separate questions:

Did the API accept the request?
What stage is the PA in?
What operational activity occurred within that stage?
If the workflow stopped, what should the caller do next?

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 PA ID.
The create request succeeds	Returned `data.id`	Store the ID and begin monitoring the resource.
The workflow progresses	`data.status`	Use the PA lifecycle state, not a placeholder outcome.
An operational event occurs	`data.activity_log` or the relevant webhook event	A fax, call, provider interaction, message, or nested operation changed. This does not necessarily change the PA state.
The workflow stops	Terminal `data.status` and `data.outcome`	Distinguish approval/denial from `not_submitted`, `failed`, and `Other`.

Lifecycle

`data.status`	Terminal	Meaning
`processing`	No	Intake, eligibility, benefit verification, form discovery, or answer prefilling is in progress. Several internal states are collapsed into this public state.
`awaiting_review`	No	Answers and evidence are ready for review before submission.
`awaiting_provider_response`	No	The prescriber or provider must supply information, answer questions, or review uploaded information.
`awaiting_outcome`	No	Submission or submission-adjacent work has begun and the request is awaiting a payer/PBM result or follow-up.
`validating_outcome`	No	A result was received and is being validated. It can return to `awaiting_outcome` if correction or follow-up is needed.
`completed`	Yes	Processing finished with an `Approved`, `Denied`, or `Other` outcome. Approval and denial are business outcomes, not errors.
`not_submitted`	Yes	The workflow stopped before a PA was sent to the payer or PBM. Inspect `outcome.detail_code`.
`failed`	Yes	An internal processing failure prevented the PA from continuing. No stable public failure-detail code is currently exposed.
`cancelled`	Yes	The request was cancelled and no further PA processing will occur.

Do not use the legacy outcome.result: "Pending" placeholder to determine whether a PA is still running.

Terminal states and outcomes

Interpret data.status before interpreting data.outcome:

Signal	Meaning
`completed` with `Approved` or `Denied`	The workflow produced a normal business outcome.
`completed` with `Other`	The workflow produced a terminal result that was neither approval nor denial. Inspect `outcome.detail_code`.
`not_submitted`	No PA was sent to the payer or PBM. Inspect `outcome.detail_code`.
`failed`	An internal failure stopped the workflow. Use a manual fallback and contact support with the PA ID.
`cancelled`	Processing was intentionally stopped.

A completed state does not by itself mean that Develop Health sent a new PA. For example, duplicate_request and prior_auth_not_required are completed Other results.

Workflow state versus activity

PA status is intentionally high-level. It does not change for every fax, call, provider interaction, or payer follow-up.

Question	Signal
What stage is the PA in, and is it terminal?	`data.status`
What fax or payer follow-up occurred?	`data.activity_log`
Was a provider communication sent, opened, started, completed, expired, or failed?	`prior_authorization.provider_outreach_change`
Why did the overall PA stop or finish without approval or denial?	`data.outcome.detail_code` or the `failed` state

A provider outreach has its own lifecycle. A single outreach becoming expired or failed does not make the parent PA terminal; a retry or escalation can create a new outreach with a new ID. Continue using the PA’s data.status for the overall workflow.

More information requests

A request for more information is not automatically terminal. While Develop Health is gathering or answering it, the PA remains in a nonterminal state such as awaiting_provider_response, awaiting_outcome, or validating_outcome. Only treat the PA as stopped when data.status itself becomes terminal. A terminal not_submitted or Other outcome can use more_information_required as its detail_code when the current workflow can no longer continue.

Request errors

Creation errors from Send Prior Authorization use the structured error response format. error.existing_prior_auth_request_id identifies an existing PA when the error refers to one; it can otherwise be null or omitted. If creation returns an error, do not start monitoring a new PA. When existing_prior_auth_request_id is present, continue monitoring that PA. The creation code other is unrelated to a completed PA whose outcome.result is Other.

`error.code`	Usual HTTP status	Meaning	Recommended handling
`unsupported_patient`	`400`	The submitted patient or payer route is not currently supported.	Use the existing PA process for this patient.
`unsupported_drug`	`400`	The submitted drug is not currently supported for PA processing.	Use the existing PA process for this drug.
`daily_prior_auth_request_limit_reached`	`400`	The organization’s daily PA request limit has been reached.	Wait for the limit to reset or use the existing PA process.
`daily_prior_auth_request_new_plan_limit_reached`	`400`	The daily limit for PA requests involving new plans has been reached.	Wait for the limit to reset or use the existing PA process.
`insurance_card_member_id_ocr_failure`	`400`	A member ID could not be extracted from the card and no discrete value was supplied.	Supply `insurance.member_id` or a clearer card image, then resubmit.
`insurance_content_invalid_rx_bin`	`400`	The structured Rx BIN is not a six-digit value.	Correct the Rx BIN and resubmit.
`prescription_message_not_found`	`400`	`prescription_message_id` does not identify a known prescription.	Verify the ID or submit the prescription data directly.
`prescription_message_already_linked`	`409`	The prescription is already linked to an in-progress or approved PA. `existing_prior_auth_request_id` identifies it.	Continue using the existing PA.
`provider_not_authorized`	`400`	The NPI is not authorized to submit PA requests.	Complete provider authorization or use the existing PA process.
`evidence_file_download_failed`	`400`	An evidence file could not be downloaded from its URL.	Fix the URL or upload the evidence another way, then resubmit.
`invalid_qle_resubmission`	`400`	A quantity-limit-exception resubmission referenced a PA that was not approved and was not marked PA-not-required.	Correct the referenced PA or submit through the appropriate PA path.
`previous_pa_request_in_progress`	`409`	The PA referenced by `resubmission_info` is not terminal. `existing_prior_auth_request_id` identifies it.	Wait for or cancel the existing PA before resubmitting.
`mock_result_not_allowed`	`400`	A production organization supplied `mock_result`, which is sandbox-only.	Remove `mock_result` and resubmit.
`invalid_diagnosis_codes`	`400`	One or more diagnosis codes are not supported ICD-10-CM codes.	Correct or remove the invalid codes, then resubmit.
`other`	Varies	An unexpected or uncategorized creation error occurred.	Use the existing PA process when urgent and contact support if it persists.
`unsupported_file_type`	`400`	A submitted file cannot be processed.	Convert or replace the file, then resubmit.
`unexpected_error`	`500`	An unexpected internal error occurred.	Use the existing PA process and contact support. Retry only if the integration can safely reconcile a duplicate request.

Some input problems are detected during creation, such as an invalid Rx BIN, an unreadable member ID, or an evidence file that cannot be downloaded. Problems discovered only after the PA is accepted appear as terminal exceptions below.

Terminal exceptions

These signals are returned by Retrieve Prior Authorization and the corresponding webhooks:

Signal	Meaning
`data.status: "failed"`	An internal processing failure stopped the PA. No stable public reason code is currently exposed.
`data.status: "not_submitted"`	No PA was sent to the payer or PBM. `data.outcome.detail_code` explains why.
`data.status: "completed"` with `data.outcome.result: "Other"`	Processing finished without approval or denial. This is not always an error; inspect `data.outcome.detail_code` and `detail`.

Not-submitted codes

`data.outcome.detail_code`	Meaning	Recommended handling
`eligibility_check_error`	Eligibility checking returned an error.	Inspect `eligibility_check_response`; correct and resubmit when its `action_code` allows it.
`eligibility_check_government_plan`	Eligibility found only government coverage.	Use the eligibility result to route the request to the appropriate submission process.
`prescription_message_not_found`	The NDP prescription message did not resolve to a valid prescription.	Verify the prescription message or use the existing manual process.
`more_information_required`	The request did not contain enough information to submit.	Read `outcome.detail`, add the missing information, and resubmit.
`formulary_alternative_required`	A formulary alternative must be used instead.	Read `outcome.detail` for the alternative and start the appropriate request.
`benefit_verification_no_medication_coverage`	A triggered BV found that the prescribed medication is not covered.	Review the BV and use an alternative or manual workflow as appropriate.
`benefit_verification_only_alternative_medication_covered`	A triggered BV found that only a submitted alternative is covered.	Use the covered alternative when clinically appropriate.
`benefit_verification_pa_not_required`	A triggered BV found that the medication does not require a PA.	No PA submission is needed.
`pbm_excluded`	Eligibility found only a PBM that is excluded from this workflow.	Use the eligibility result and an alternate submission process.
`payer_not_supported`	Eligibility found a health plan that is not supported.	Use an alternate submission process.

Other result codes

data.outcome.result: "Other" means the terminal result is neither approval nor denial. It does not mean an unclassified request error occurred.

`data.outcome.detail_code`	Meaning	Recommended handling
`coverage_inactive`	The patient’s coverage has expired.	Verify current coverage before starting another PA.
`coverage_not_yet_started`	Coverage exists but is not yet effective.	Wait until coverage is effective or use the appropriate current plan.
`no_pharmacy_benefits`	The insurance does not include pharmacy benefits.	Verify the benefit and use an alternate coverage or fulfillment path.
`payer_unable_to_locate_member`	The payer could not locate the member.	Correct the member and insurance information before starting another PA.
`npi_taxonomy_ineligible`	The prescriber’s NPI taxonomy, provider type, specialty, or credentials are not eligible for this PA.	Use an eligible provider or resolve the provider record with the payer.
`payer_reported_invalid_patient_info`	The payer located the member, but submitted patient information does not match.	Correct the patient information before starting another PA.
`duplicate_request`	The request duplicates an existing PA.	Locate and continue tracking the existing PA.
`prior_auth_not_required`	The medication does not require a PA.	Do not start another PA for this prescription and coverage.
`patient_consent_required`	The payer requires verbal consent from the patient.	Obtain consent, then use the appropriate resubmission or manual process.
`more_information_required`	More information is needed to complete the PA.	Read `data.outcome.detail`, collect the missing information, and use the appropriate resubmission path.
`other`	No more specific public code applies.	Read `data.outcome.detail`; use a manual fallback and contact support with the PA ID when the next step is unclear.

Eligibility-check errors

When enabled, data.eligibility_check_response contains one item per result. An error item has status: "error", an error_code, a human-readable error_message, and an action_code.

`error_code`	Meaning
`provider_not_on_file`	The payer has no record of the supplied provider ID; the provider must register the NPI with the payer.
`patient_birth_date_does_not_match_database`	The submitted date of birth does not match the payer’s member record.
`invalid_missing_subscriber_insured_id`	The member ID is missing, malformed, fails payer validation, or does not satisfy payer requirements.
`subscriber_insured_not_found`	The payer could not locate a member matching the submitted ID, name, and date of birth.
`duplicate_subscriber_insured_id_number`	The member ID matches multiple people and the inquiry is ambiguous.

`action_code`	Meaning
`please_correct_and_resubmit`	Correct the invalid or missing data and resubmit.
`resubmission_not_allowed`	The payer will not accept the same inquiry again; resolve the issue directly with the payer.

Retrieve errors

Retrieve Prior Authorization returns 404 when the PA does not exist or is not visible to the authenticated organization.

Nested operations

Nested work has its own lifecycle and errors and does not change the meaning of the parent PA state. If data.prescription_transfer is populated, see Cancel Prior Authorization Prescription Transfer for its states and error codes.

Monitoring and unknown values

Use the retrieve endpoint or prior_authorization.status_change webhook to monitor the lifecycle. Other event types describe messages, provider outreach, and prescription transfer; receiving one does not mean the PA is terminal. Treat code lists as extensible. Preserve unknown codes in logs and handle them like other rather than failing to parse the response. See Understanding API Responses for common authentication and validation errors.

Getting Started

Benefit Verification