Error Codes and Troubleshooting

How Errors Work

If the Nirvana API can't process a request, it will return an HTTP response code in the 4xx or 5xx range. The response body will include the following fields:

error – A code indicating what went wrong (ex. UNKNOWN_REMAININGS )
message – An easily-interpretable explanation of the issue (ex. "Unable to determine remaining deductible." or "Unable to determine remaining oop max.")

Use the error code to write robust error-handling logic, and refer to message when troubleshooting or debugging.

In some cases, the response may also include an errors array that lists multiple issues. When this happens, the error and message fields will still be included at the top level for convenience.

It's possible to receive a response that contains both a result and an error, indicating a partial or best-effort response. Check for the presence of an error field before assuming the result is fully valid.

Error responses generally follow this shape:

{
  "error": "error category",
  "message": "cause of the error + next steps",
  "details": {
    "validation_failures": [...],
    "suggested_payer": "..."
  }
}

403 Forbidden

A 403 Forbidden response usually means one of the following:

Your API key is missing, expired, or incorrect
You used an incorrect HTTP method (e.g., GET to a POST endpoint)
Your IP address was blocked due to security filters or rate limiting

Nirvana uses layered security protections to help keep our systems safe. If you believe you're being blocked in error, contact [email protected] for review.

Error Codes by Endpoint

Nirvana returns different error codes/status code combinations based on the endpoint used, please see the table for detailed error code and troubleshooting guide for each endpoint:

Estimate
Discover
Medicaid
Scan

Estimate

Error Code	Status Code(s)	Meaning	Troubleshooting
`UNKNOWN_REMAININGS`	206	The plan was found, but the payer didn't return a usable deductible or OOP max amount.	Treat member obligation as unconfirmed, use response.error_message to determine if OOP Max or Deductible is unknown. Consider a manual check via payer portals or contact the payer directly to get remainings details.
`UNKNOWN_COSTSHARE`	206	The plan was found, but the payer didn't return a usable copay or coinsurance amount.	Cost-share wasn't returned by the payer. Flag the plan for manual review or contact the payer for additional information.
`CANNOT_CALCULATE_MEMBER_OBLIGATION`	206	This error happens when Nirvana is unable to calculate the member obligation (how much the patient owes for the service). Some scenarios that trigger this include: copay returned is higher than the session rate provided, or patient is close to meeting their deductible. When the deductible is not met but remaining deductible is less than the cost of one session, the visit cost could be split pre- and post-deductible, making it difficult to calculate exact member obligation.	Double-check the session rate submitted in the request, or check if the deductible is close to being met. response.error_message will give more detail on what triggered the error.
`ERROR_PROCESSING_FINANCIALS`	206	The patient's plan is active, but Nirvana cannot determine if the requested service (e.g. behavioral health services) is covered under this plan.	Contact the payer directly to confirm coverage for a particular service type.
`MEMBER_NOT_FOUND`	404	The payer has no record matching the member ID and demographics submitted.	Verify member ID and DOB against the insurance card. If error.details includes a suggested_payer, retry with that payer ID instead.
`PAYER_NOT_SUPPORTED`	400	This payer isn't in Nirvana's supported payer list yet.	This payer isn't supported yet. Contact your CSM to request it be added. Don't retry the same request.
`PAYER_FAILURE`	502	The payer's system is temporarily unreachable or down.	Likely a temporary payer-side outage. We recommend retrying the request in 1 hour; if the error persists past 24 hours, please contact Nirvana Support.
`TIMEOUT`	502	The coverage request to the payer timed out.	Likely a temporary payer-side outage. We recommend retrying the request in 1 hour; if the error persists past 24 hours, please contact Nirvana Support.
`TIMEOUT`	504	The request to connect to Nirvana's API timed out.	Please try again in 5 minutes. If the problem persists past 2 hours, please contact Nirvana Support.
`PROVIDER_NOT_RECOGNIZED`	400	The payer doesn't recognize this provider NPI — either an enrollment gap or a credentialing issue.	Try a different NPI (e.g., group vs. individual) or contact Nirvana Support to check enrollment for your NPI. If it's a credentialing gap, you may need to contact the payer directly.
`UNKNOWN_PLAN_STATUS`	400	Nirvana couldn't determine whether the plan is currently active or whether it covers mental health benefits.	Contact the payer directly to confirm patient plan status. Retrying is unlikely to change the result.

Discover

Error Code	Status Code(s)	Meaning	Troubleshooting
`MEMBER_NOT_FOUND`	404	The payer has no record matching the member ID and demographics submitted.	Verify member ID and DOB against the insurance card. If error.details includes a suggested_payer, retry with that payer ID instead.
`UNKNOWN_COSTSHARE`	200, 404	The plan was found, but the payer didn't return a usable copay or coinsurance amount.	Cost-share wasn't returned by the payer. Use a placeholder/manual estimate until confirmed, and flag the plan for review if this recurs.
`UNKNOWN_REMAININGS`	200, 404	The plan was found, but the payer didn't return a usable deductible or OOP max amount.	Treat cost-share as unconfirmed; consider a manual check via payer portals or call the payer directly.
`UNKNOWN_PLAN_STATUS`	200, 404	Nirvana couldn't determine whether the plan is currently active or whether it covers mental health benefits.	Contact the payer directly to confirm — retrying is unlikely to change the result.
`CANNOT_CALCULATE_MEMBER_OBLIGATION`	200	This error happens when Nirvana is unable to calculate the member obligation (how much the patient owes for the service). Some scenarios that trigger this include: copay returned is higher than the session rate provided, or patient is close to meeting their deductible. When the deductible is not met but remaining deductible is less than the cost of one session, the visit cost could be split pre- and post-deductible, making it difficult to calculate exact member obligation.	Double-check the session rate submitted in the request, or check if the deductible is close to being met. response.error_message will give more detail on what triggered the error.
`PAYER_FAILURE`	502	The payer's system is temporarily unreachable or down.	Temporary payer-side outage. Nirvana automatically retries in 1 hour; no action needed unless it persists past 24 hours — then contact Support.
`TIMEOUT`	502	The coverage request to the payer timed out.	Likely a temporary payer-side outage. We recommend retrying the request in 1 hour; if the error persists past 24 hours, please contact Nirvana Support.
`MISMATCH_ZIP_CODE`	400, 404	The ZIP code submitted doesn't match what the payer has on file for this member.	Double-check the ZIP code submitted matches the patient's current address on file, then resubmit.
`MISMATCH_MEMBER_NAME`	400, 404	The member name submitted doesn't match what the payer has on file.	Double-check spelling and confirm you're using the member's legal name as it appears on the insurance card, then resubmit.
`MISMATCH_MEMBER_DATE_OF_BIRTH`	400, 404	The date of birth submitted doesn't match what the payer has on file for this member.	Double-check the DOB format and that it matches the payer's records, then resubmit.
`PROVIDER_NOT_RECOGNIZED`	400	The payer doesn't recognize this provider NPI — either an enrollment gap or a credentialing issue.	Try a different NPI (e.g., group vs. individual) or contact Nirvana Support to check enrollment for your NPI. If it's a credentialing gap, you may need to contact the payer directly.

Medicaid

Error Code	Status Code(s)	Meaning	Troubleshooting
`MEMBER_NOT_FOUND`	404	The payer has no record matching the member ID and demographics submitted.	Verify member ID and DOB against the insurance card. If error.details includes a suggested_payer, retry with that payer ID instead.
`PAYER_FAILURE`	502	The payer's system is temporarily unreachable or down.	Temporary payer-side outage. We recommend retrying the request in an hour; if the issue persists past 24 hours, please contact Nirvana Support.
`TIMEOUT`	502	The coverage request to the payer timed out.	Likely a temporary payer-side outage. We recommend retrying the request in 1 hour; if the error persists past 24 hours, please contact Nirvana Support.
`PROVIDER_NOT_RECOGNIZED`	400	The payer doesn't recognize this provider NPI — either an enrollment gap or a credentialing issue.	Try a different NPI (e.g., group vs. individual) or contact Nirvana Support to check enrollment for your NPI. If it's a credentialing gap, you may need to contact the payer directly.
`PAYER_NOT_SUPPORTED`	400	This payer isn't in Nirvana's supported payer list yet.	This payer isn't supported yet. Contact Nirvana Support to request it be added. Don't retry the same request.
`ERROR_RETRIEVING_COVERAGE`	400	The payer didn't return a usable response, and Nirvana can't confirm coverage information for this plan.	Double-check member ID, DOB, and legal name, then resubmit. If it still fails after correcting patient data, contact Support.
`UNKNOWN_PLAN_STATUS`	400	Nirvana couldn't determine whether the plan is currently active or whether it covers mental health benefits.	Contact the payer directly to confirm plan status. Retrying is unlikely to change the result.
`INVALID_INPUT`	422, 404	A required field (e.g., patient name) is missing or malformed in the request.	A required field is missing or malformed. Check your request against the API reference for required fields and formatting.
`UNEXPECTED_ERROR`	500	An unexpected server-side error occurred while processing the request.	Transient server-side error. Retry after a short delay; contact Support with the request ID/timestamp if it persists beyond an hour.
`TOO_MANY_REQUESTS`	429	The API key has exceeded the rate limit (50 requests/minute).	Rate limit hit. Please retry requests after a minute.

Scan

Error Code	Status Code(s)	Meaning	Troubleshooting
`UNABLE_TO_FIND_ACTIVE_COVERAGE`	404	No active policy could be found for this member.	Confirm the member's ZIP/demographics, or try Estimate/Discover if you have a member ID or payer.
`PAYER_FAILURE`	502	The payer's system is temporarily unreachable or down.	Temporary payer-side outage. We recommend retrying the request in an hour; if the issue persists past 24 hours, please contact Nirvana Support.
`TIMEOUT`	502	The coverage request to the payer timed out.	Likely a temporary payer-side outage. We recommend retrying the request in 1 hour; if the error persists past 24 hours, please contact Nirvana Support.
`MISMATCH_ZIP_CODE`	400	The ZIP code submitted doesn't match what the payer has on file for this member.	Double-check the ZIP code submitted matches the patient's current address on file, then resubmit.
`MISMATCH_MEMBER_NAME`	400	The member name submitted doesn't match what the payer has on file.	Double-check spelling and confirm you're using the member's legal name as it appears on the insurance card, then resubmit.
`MISMATCH_MEMBER_DATE_OF_BIRTH`	400	The date of birth submitted doesn't match what the payer has on file for this member.	Double-check the DOB format and that it matches the payer's records, then resubmit.
`INVALID_INPUT`	404, 422	A required field (e.g., patient name) is missing or malformed in the request.	A required field is missing or malformed. Check your request against the API reference for required fields and formatting.
`TOO_MANY_REQUESTS`	429	The API key has exceeded the rate limit (50 requests/minute).	Rate limit hit. Please retry requests after a minute.