Quote and Member Exception Codes

Catalogue of exception codes returned in the quote_exceptions and member_exceptions arrays

Pre-release documentation — The v9 group quoting endpoints are actively in development and not yet available in production. This documentation is published early so integrators can plan and scope ahead of release. Endpoint behavior, field names, and response shapes may change before general availability. For the current development status and target release date, see the Product Release Notes. To integrate against the stable version today, see the v8 documentation in Previous Versions.

The v9 Display Rates response surfaces plan eligibility and quoting errors inline with premiums, as objects in the quote_exceptions and member_exceptions arrays on each plan. This page is the complete catalogue of exception codes that can be returned across all group quoting product lines — Small Group Medical, Level Funded, and Ancillary. For the full structure of these arrays and the fields on each exception object, see the Retrieve Premium and Eligibility Results section.

In most scenarios, exceptions are warnings rather than errors. v9 attempts to quote every plan available to the group based on service area, and premiums are returned alongside exceptions when the underlying census and quote data are valid. The quote_exceptions array flags issues that apply to the group as a whole (such as group size or SIC code restrictions); the member_exceptions array flags individual members or dependents that may not be eligible for coverage under the plan. We highly recommend surfacing exceptions to end users or operational support teams, as they commonly indicate that the group or its members may not be eligible to enroll given the configured underwriting guidelines.

Exceptions do not always come with premiums. When quote_impacted is true on a quote_exception, premiums could not be returned for the plan — typically because of a carrier API error or missing data required for quoting. These cases require action before the group can be successfully quoted for the affected plans and are detailed in the Triage guidance section below.

• Quote Exception Codes

• Member Exception Codes

• Triaging Exceptions that Prevent Quoting

• Migrating from v8 Limiting Factors

Quote Exception Codes

The following codes can appear in the quote_exceptions array. These exceptions flag validations that impact the group as a whole or a plan's ability to be quoted for the group. When the quote_impacted field on a quote exception is true, premiums could not be returned for the plan — refer to the Triaging Exceptions that Prevent Quoting section below for guidance on resolving these cases.

The Primary Product Line(s) column is left blank for codes that apply generally across all group quoting product lines. Product lines are listed only for codes that are narrowly scoped to specific products in practice today.

The message field on each exception is constructed with as much specific information as possible based on the quote, census, and business rule data available at the time the exception was evaluated. The example messages in the table illustrate the fully-populated form; shortened variants of a given message may be returned in scenarios where specific values are not available.

This list of codes is not exhaustive for future product and carrier support. Additional quote exception codes may be added over time as Ideon's business rule logic expands and new carrier integrations are supported. This page will be updated with any additions.

Code	Primary Product Line(s)	Description	Example Message
contribution_percentage_minimum		The quoted contribution percentage is below the minimum required by the carrier for the plan.	The quoted contribution of 50% does not meet Cigna's minimum contribution requirement of 75% for this plan.
participation_percentage_minimum		The quoted participation percentage is below the minimum required by the carrier for the plan.	The estimated participation of 60% does not meet Aetna's minimum participation requirement of 75% for this plan.
enrollee_size_minimum	Ancillary	The estimated number of enrolling members, calculated from the group size and participation percentage, is below the minimum required for the plan.	The estimated number of 3 enrolling members does not meet Ambetter's minimum of 5 enrolling members for groups of 2 to 50 for this plan. The estimated number of enrolling members is calculated from the group size of 5 and the participation percentage of 60%.
group_size_minimum		The group's size is below the minimum required for the plan.	This group's size of 3 members does not meet the minimum group size of 5 members for this plan.
group_size_maximum		The group's size exceeds the maximum allowed for the plan.	This group's size of 120 members exceeds the maximum group size of 100 members for this plan.
sic_code		The group's SIC code is not eligible under the carrier's rules for the plan.	This plan is not available to groups with SIC code 0700 based on Anthem's eligibility rules.
voluntary_status	Ancillary	The quoted voluntary status is inconsistent with the carrier's requirements for the plan.	The quoted voluntary status is inconsistent with Humana's requirements for this plan.
effective_date_minimum		The carrier's API does not support quoting for the requested effective date because it is earlier than the minimum supported date.	UnitedHealthcare's API does not support quoting for the requested effective date of 2025-01-01. Carrier APIs typically do not support quoting of past effective dates or future effective dates that are not open for enrollment.
effective_date_maximum		The carrier's API does not support quoting for the requested effective date because it is later than the maximum supported date.	Humana's API does not support quoting for the requested effective date of 2027-06-01. Carrier APIs typically do not support quoting of past effective dates or future effective dates that are not open for enrollment.
in_state_percentage_minimum	Medical	The percentage of members residing in the rated state is below the minimum required for the plan. These rules are rare and currently only apply to plans in California, which generally requires over 50% of group members to reside in-state.	40% of the group's members reside in CA, which does not meet Oscar's minimum in-state residency requirement of 50% for this plan.
multi_state_percentage_minimum	Medical	The percentage of members residing in the carrier's required states is below the minimum for the plan. These rules are rare and currently only apply to Select Health plans in ID, NV, and UT, which require 50% of members to reside in one of those states.	35% of the group's members reside in Idaho, Nevada, and Utah, which does not meet Select Health's minimum residency requirement of 50% for this plan.
member_name	Level Funded	One or more members in the census are missing a first_name or last_name required by the carrier to quote the plan.	This plan could not be quoted because one or more members in the census are missing a first_name or last_name, which are required by Angle for this plan. Affected members (by external_id): 001, 003.
member_salary	Disability	One or more members in the census are missing an annual_salary or hours_per_week required by the carrier to quote the plan.	This plan could not be quoted because one or more members in the census are missing an annual_salary or hours_per_week, which are required by Beam for this plan. Affected members (by external_id): 001, 003.
invalid_npn		The broker or agency NPN associated with the group is considered ineligible for quoting by the carrier. NPNs are exclusively validated by certain carrier API integrations for real-time quoting.	UnitedHealthcare considers the broker NPN of 1234567890 ineligible for quoting. Please verify the NPN is correct and that the broker or agency is appointed with UnitedHealthcare, then re-quote. If the issue persists, contact Ideon Support or UnitedHealthcare directly.
carrier_api_error		The carrier's API returned an error when Ideon attempted to quote the plan. The exception object will include a carrier_api_error_messages array containing the raw error strings returned by the carrier's API.	The quote request to UnitedHealthcare's API returned a 500 error. Please retry the quote and, if the error persists, contact Ideon Support.
carrier_api_timeout		The carrier's API did not respond within the retry window. The window is configurable via the retry_until parameter on the Create a Quote request.	Optimyl's API did not respond within the retry window. Please retry the quote and, if the error persists, contact Ideon Support.

Member Exception Codes

The following codes can appear in the member_exceptions array. These exceptions flag validations that apply to specific members or their dependents, not the group as a whole. Premiums are still returned for members with member exceptions — the exception is informational and indicates the member or dependent may not be eligible for coverage under the plan.

This list of codes is not exhaustive for future product and carrier support. Additional member exception codes may be added over time as Ideon's business rule logic expands and new carrier integrations are supported. This page will be updated with any additions.

Code	Primary Product Line(s)	Description	Example message
member_age_minimum		The member is below the minimum age allowed for the plan, based on their age at the quote's effective date.	Member with external_id: 001 is below Blue Cross Blue Shield's minimum age of 18 for this plan. The member's age is calculated at the quote's effective date of 2026-01-01 given their date of birth of 2010-05-15. Premiums for this member are included in the plan total, but they may not be eligible for coverage.
member_age_maximum		The member exceeds the maximum age allowed for the plan, based on their age at the quote's effective date.	Member with external_id: 001 exceeds Humana's maximum age of 64 for this plan. The member's age is calculated at the quote's effective date of 2026-01-01 given their date of birth of 1955-03-12. Premiums for this member are included in the plan total, but they may not be eligible for coverage.
member_location	Medical	The member's residence or work location does not meet the carrier's eligibility requirements for the plan, typically because they fall outside the plan's service area. This rule is rare and currently only applies to some California plans. Defaulting all member locations to the group's primary location will avoid triggering this exception.	Member with external_id: 001, residing in NY (zip code: 10010, FIPS code: 36061) and working in NJ (zip code: 07302, FIPS code: 34017), does not meet Aetna's eligibility requirements for this plan. Premiums for this member are included in the plan total, but they may not be eligible for coverage.
dependent_age_minimum		One or more of the member's dependents are below the minimum age allowed for the plan, based on their age at the quote's effective date. The dependent_exceptions array on the exception object identifies which dependents are affected.	Member with external_id: 001 has dependent(s) aged 10, 12 at the quote's effective date, which are below Oscar's minimum age of 14 for this plan. Premiums for these dependents are included in the plan total, but they may not be eligible for coverage.
dependent_age_maximum		One or more of the member's dependents exceed the maximum age allowed for the plan, based on their age at the quote's effective date. The maximum covered age for child dependents is 25 for most medical plans, though this can be higher for specific carriers or plan-specific riders; nuanced allowances based on disability, school enrollment, or continued household residence are not evaluated. The dependent_exceptions array on the exception object identifies which dependents are affected.	Member with external_id: 001 has dependent(s) aged 26, 28 at the quote's effective date, which exceed Cigna's maximum age of 25 for this plan. Premiums for these dependents are included in the plan total, but they may not be eligible for coverage.
dependent_location	Medical	One or more of the member's dependents have a same_household value that is not allowed for the plan. Most medical plans require dependents to live in the same household as the member, though carrier-specific exceptions exist. The dependent_exceptions array on the exception object identifies which dependents are affected.	Member with external_id: 001 has dependent(s) that do not meet Kaiser Permanente's relationship or household requirements for this plan. Affected dependents (relationship, same_household): (step_child, false). Premiums for these dependents are included in the plan total, but they may not be eligible for coverage.
dependent_relationship	Medical	One or more of the member's dependents have a relationship type that is not allowed for the plan. The allowed set varies by carrier and plan, but most medical plans accept adopted_child, child, court_appointed_guardian, disabled_child, foster_child, life_partner, spouse, step_child, and ward. The dependent_exceptions array on the exception object identifies which dependents are affected.	Member with external_id: 001 has dependent(s) with a relationship type that is not allowed under Anthem's requirements for this plan. Affected dependents (relationship, same_household): (sibling, true). Premiums for these dependents are included in the plan total, but they may not be eligible for coverage.

Triaging Exceptions that Prevent Quoting

Triage guidance is focused on exceptions that commonly prevent premiums from being returned for a plan. These exceptions are surfaced in the quote_exceptions array with quote_impacted set to true, meaning the plan is included in the Display Rates response without premiums.

Carrier API Quoting Errors

Real-time carrier API integrations are supported for Small Group Medical (UnitedHealthcare), Level Funded (UnitedHealthcare, Optimyl Benefits, and Angle Health), and Ancillary (UnitedHealthcare, Beam, Humana, and Principal). The failure modes described in this section apply to any carrier API integration, though the specific guidance below focuses on UnitedHealthcare's API as the most established integration and the most common source of these exceptions.

• Invalid NPN invalid_npn — some carriers validate the broker or agency NPN against their appointed list and reject quote requests for unappointed producers. The NPN associated with the quote is determined by the group's broker_npn or agency_npn field (broker_npn takes precedence when both are provided). There is no way to bypass this validation at the Ideon API level; the producer must be appointed with the carrier to be able to quote. Currently, UnitedHealthcare and Humana are the only carriers that validate NPNs in this way.

• Timeout errors carrier_api_timeout — quote requests to carrier APIs are automatically retried for up to 15 seconds by default, configurable via the retry_until parameter on the Create a Quote request. If requests are not completed in that time, a timeout exception is returned. Timeouts most commonly indicate rare, intermittent periods of carrier downtime lasting 1–2 minutes. If a timeout exception is returned, we recommend waiting 2 minutes and retrying the quote.

• General API errors carrier_api_error — for any generic or unmapped quoting error returned by a carrier's API, a carrier API error exception is returned. The raw error strings from the carrier are passed directly into the carrier_api_error_messages array on the exception object. There are two scenarios in which this can happen:

  • Unmapped quoting errors — carrier APIs can have large error code vocabularies. The majority of these are mapped to standardized Ideon exception codes for ease of use. If a new or unexpected error code is returned by the carrier, it will surface as a carrier API error exception with the raw carrier strings attached.

  • General quoting errors — during rare periods of downtime, a carrier's API may respond with 30X or 50X response codes. In these cases, similar to timeout errors, we recommend waiting 2 minutes and retrying the quote.

Missing Census Data

The member_name and member_salary exceptions indicate that required census fields are missing for one or more members, preventing the plan from being quoted. These are quote_exceptions with quote_impacted: true — premiums are not returned for the plan until the census is updated and the group is re-quoted. The exception's message field identifies the affected members by their external_id so the specific census records can be updated.

• member_name is triggered when a carrier requires first_name and/or last_name for quoting and one or more members are missing either field. Currently only triggered for Angle Health Level Funded quoting.

• member_salary is triggered when a carrier requires annual_salary and/or hours_per_week for quoting and one or more members are missing either field. Currently only triggered for Beam Disability quoting.

Migrating from v8 Limiting Factors

Customers integrating to the v8 Show Limiting Factors endpoint will notice the following changes when moving to v9 exceptions. The complete integration guide for v9 SG Quoting can be found in the Small Group Medical section.

• Structural change. Exceptions are now returned inline on each plan's rate object in the Display Rates response, rather than on a separate /limiting_factors endpoint. The v8 code_description field has been replaced with a message field that contains a plain-language message constructed with specific values from the quote, census, and business rules.

• Classification change. The member_name and member_salary codes have been reclassified from member limiting factors in v8 to quote_exceptions in v9. These exceptions prevent the plan from being quoted for the group as a whole (rather than flagging individual members), so they are grouped with other quote-level exceptions with quote_impacted set to true.

• No behavior change for members flagged by business rules. In v8, members flagged as ineligible for a plan could be omitted from quotes unless include_member_limited_plans was set to true. In v9, the include_member_limited_plans parameter has been deprecated and all members are always included in quotes. Plans are still quoted with premiums and the flagged members surface through member_exceptions inline with the plan's rate object.

• Source is now explicit. Each exception includes a source field (carrier_api, ideon_business_rules, or ideon_rating_engine) indicating the system that flagged the exception. In v8, the source was implicit based on the code value.