> ## 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. # Prior Authorization Response Handling > How to interpret request errors, PA lifecycle states, activity, and terminal exceptions. Prior authorization responses answer four separate questions: 1. Did the API accept the request? 2. What stage is the PA in? 3. What operational activity occurred within that stage? 4. 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](/api-reference/prior-authorization/webhooks) | 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`](/api-reference/provider-outreach-webhooks) | | 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](/api-reference/prior-authorization/post) use the structured [error response format](/api-reference/response-handling#error-response-formats). `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](/api-reference/prior-authorization/get_item) 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](/api-reference/prior-authorization/get_item) 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](/api-reference/prior-authorization/post_prescription_transfer_cancel) 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](/api-reference/response-handling) for common authentication and validation errors.