Error Codes

Errors are returned in the common error envelope. Branch on code, not on message; message changes with the language. Envelope fields and general rules: Error Handling.

{
  "status": "failure",
  "code": "insurance.validation.invalid",
  "message": "The insurance request is invalid — see `details.errors`.",
  "statusCode": 422,
  "requestId": "00000000-0000-0000-0000-000000000000",
  "details": {
    "errors": [{ "field": "currency", "reason": "currency_mismatch" }]
  }
}

When an error response carries a docsUrl field, it points to the description of the code on this page.

Codes have the form insurance.<area>.<reason> and each has a single meaning. Details are in details: details.errors[] for field violations, details.reason for state conflicts, details.retryable: true for retryable errors. The personal data you send, the provider's codes and its raw messages are not included in error responses.

Summary

API requests

Codes seen on the order and in webhooks

Policy, cancellation and refund work runs in the background after your request. Errors of this work do not appear in the request's response but in the order's errorCode or refundErrorCode field and in the errorCode field of the webhook payload.

The quote stage codes (insurance.quote.declined, insurance.reference.unknown, insurance.validation.invalid) may also appear as errorCode during the policy work; their meanings are as below.

Panel

Checkout Form

Quote and eligibility

insurance.validation.invalid

The request does not follow the insurance rules: a missing or malformed field, a timestamp without a time zone, a decimal amount, an unknown field. All violations come in a single response in details.errors[]; each item carries field (the field path, e.g. tickets[0].departureAt) and reason. The value you sent is not written to the response.

Common reasons:

The list of reasons may grow; treat an unknown reason as the field being invalid. Fix the request and send it again. Formats: Data Formats.

insurance.reference.unknown

A reference code in the request (e.g. country, city, district) is not recognized or has no counterpart for your connection's provider. The field path is in details.errors[].field (reason: unknown_reference), the reference kind in details.kind. Take valid codes from the GET /api/v1/insurance/reference/{kind} endpoint; do not send guessed or empty values.

insurance.type.not_available

The requested insurance type cannot be offered right now: the type is not enabled for your account, the basket does not meet the eligibility conditions, none of your connections has an enabled product for this type, or a type sold only with a basket item was requested without one (Selling Without a Basket Item). Get the eligible types from the Eligibility endpoint.

The same code is returned for lead types: a quote was requested for a lead type, the type in a lead request is not a lead type, or none of your connections has a product that accepts leads for this type. See Leads.

insurance.quote.declined

The provider did not give a quote for these details. Retrying with the same details does not change the result. You can continue the payment without insurance.

insurance.quote.not_found

The quote or option was not found: the ID is wrong or belongs to another account. Take the ID exactly as returned by Quotes.

insurance.quote.expired

The quote's validity period has ended. Get a new quote and create the order with the new option.

insurance.quote.stale

The quote is out of date: the basket, the insured items or the insured details changed after the quote. For example, the payment's insured items differ from the quoted items. Get a new quote.

insurance.facility.not_supported

A contracted facility list is not available for this option: the product of the option in your connection does not provide a facility list. The request is not sent to the provider. Retrying does not change the result; the option is not affected. See Quotes › Contracted facilities.

Basket item pre-fill data

There is no separate error code for the basket item's insurance pre-fill data (insuranceData). Pre-fill data appears in these responses:

Order and payment

insurance.order.not_found

The order was not found: the ID is wrong or belongs to another account. Order IDs start with the inso_ prefix.

insurance.order.state_conflict

The order's state does not allow the operation; for example, the order is bound to another payment, the policy has not been issued yet, or the refund is already completed. The reason is in details.reason. Retrying the same request does not change the result.

Meaning of the reasons: Orders and Payment Binding › State conflict, and for cancellation and refund Cancellation and Premium Refund.

insurance.order.premium_item_mismatch

The premium item in the payment's basket does not match the order. The premium item must be present exactly once: id is the order ID, itemType is VIRTUAL, a single unit, and the amount is the premium. The reason is in details.reason: Orders and Payment Binding › Binding to a payment.

insurance.order.payment_not_recorded

The payment's basket is not recorded for insurance: the payment was not created with insured items, or insurance was not enabled on your account when the payment was created. Create the payment with insured items: Premium and Payment.

insurance.idempotency.conflict

The same Idempotency-Key was already used with a different request. Generate a new key for a new operation; if you are repeating the same operation, send the body of the first request unchanged. See Flows › Idempotency-Key.

insurance.premium.not_captured

The premium has not been collected.

• In a request's response: The policy or a premium refund was requested before the premium was collected. Wait for the premium to be collected first.
• On the order and in webhooks (errorCode): The payment was cancelled, expired or finally failed before it was captured. Collection becomes FAILED and the policy is not requested. No refund is needed because no premium was taken.

Provider collection

Codes seen on orders whose premium the provider collects. Flow: Provider Collection.

insurance.payment.merchant_payment_not_captured

The premium cannot be charged because the Lunixi payment bound to the order is not captured yet. No payment is sent to the provider before your payment is taken. Repeat the request after the payment is captured.

insurance.payment.method_not_supported

Provider collection cannot be used in the requested way for this order. The reason is in details.reason: Provider Collection › Unsupported collection. Retrying the same request does not change the result.

insurance.card.invalid

The card details are invalid: the card number fails validation, the card has expired or a field has the wrong format. The invalid field is in details.field; card values never appear in the error response. No request is sent to the provider. Fix the field and send again.

insurance.card.pci_required

The product charges the premium by card, but your account is not registered as PCI-DSS certified. Only PCI-DSS certified merchants may send raw card data to the API. The card is not processed or stored and no request is sent to the provider. Retrying the same request does not change the result: Provider Collection › Card details.

insurance.payment.declined

The provider declined the premium charge. This code appears in the charge attempt's failureCode, the order's errorCode and the errorCode of the insurance.policy.failed payload. Collection becomes FAILED and the policy is not requested; your payment stays valid. If the buyer wants to try another card, you can start a new attempt with a new Idempotency-Key.

insurance.payment.not_found

The provider payment address the buyer was redirected to is no longer valid: the return was processed or the attempt is not waiting for the buyer. Track the order on the order endpoint.

Policy, cancellation and refund

insurance.policy.not_found

The policy was not found: the ID is wrong or belongs to another account. Take the policy ID from the order's policies[] array.

insurance.policy.issue_failed

The provider did not issue the policy, finally; it is not retried automatically. On the order, the policy becomes FAILED_FINAL. If the premium was collected, the refund becomes REQUIRED and the premium has to be refunded: Cancellation and Premium Refund › Refund required.

insurance.policy.issue_deadline_passed

The policy could not be issued before the product's deadline (e.g. the coverage start); no new policy is issued after this time. On the order, the policy becomes FAILED_FINAL. If the premium was collected, the refund becomes REQUIRED.

If the provider issued the policy before this time and the outcome is finalized later, the policy becomes ISSUED and insurance.policy.issued is sent, provided the refund has not started. See Webhook Events.

insurance.policy.cancel_failed

The provider finally rejected the cancellation request (e.g. the coverage has started or the cancellation period has passed). The policy stays in force: the order's policy status becomes ISSUED or PARTIALLY_ISSUED. The cancellation is not retried automatically. See Cancellation and Premium Refund › Policy cancellation.

insurance.refund.rejected

The premium refund could not be made on the payment side; no money moved. On the order, the refund becomes FAILED and the code is written to refundErrorCode. You can start the refund again with the premium refund endpoint or make it through your own channel.

Claims

Codes seen on the claim endpoints. Flow: Claims.

When a claim fails finally, the reason is also in the claim's errorCode field and in the claim.errorCode field of the insurance.claim.failed payload: insurance.claim.rejected or insurance.provider.unavailable.

insurance.claim.not_found

The claim was not found: the ID is wrong or belongs to another account. A claim ID starts with the insclm_ prefix.

insurance.claim.state_conflict

The state of the policy or the claim does not allow this action; for example, the policy is not in force, the policy has an open claim or the claim whose document was requested did not reach the provider. The reason is in details.reason. Retrying the same request does not change the result.

Meaning of the reasons: Claims › State conflict.

insurance.claim.not_supported

A claim cannot be filed for this policy: the policy's insurance type or the product in your connection does not support claims. Retrying does not change the result. See Claims › Policies that accept a claim.

insurance.claim.rejected

The provider did not accept the claim. The claim becomes FAILED and insurance.claim.failed is sent. Retrying the same request does not change the result. If needed, you can file a new claim with a new Idempotency-Key.

Leads

Codes seen on the lead endpoints. Flow: Leads.

When a lead fails finally, the reason is also in the lead's errorCode field: insurance.lead.rejected, insurance.validation.invalid or insurance.provider.unavailable.

insurance.lead.not_found

The lead was not found: the ID is wrong or belongs to another account. Lead IDs start with the insl_ prefix.

insurance.lead.rejected

The provider did not accept the lead. The lead becomes FAILED; details.leadId carries its ID. Retrying the same request does not change the result. You can correct the details and submit a new lead with a new Idempotency-Key.

Document

insurance.document.not_supported

The requested document type is not available for this policy: the product of the policy in your connection does not provide a receipt or a certificate. The request is not sent to the provider. Retrying does not change the result; the policy document is not affected. See Policy Document › Receipt, Certificate.

insurance.document.unavailable

The policy document or the provider's claim document cannot be retrieved from the provider right now (details.retryable: true). The policy and the claim stay valid; their statuses do not change. Repeat the request after a while, increasing the wait between retries. See Policy Document, Claims › The provider's claim document.

Connection and provider

insurance.provider.unavailable

Your connection's provider cannot be reached right now (details.retryable: true). The request is not passed to another provider. Retry after a while, increasing the wait between retries.

insurance.provider.not_integrated

This operation is not available right now for your connection's provider (e.g. connection test, cancellation or document). Retrying does not change the result.

insurance.provider.not_configured

Your connection's provider is not ready for use in this environment right now. There is nothing to fix in your request. If the problem persists, contact support with the requestId from the response.

insurance.connection.not_found

The insurance connection was not found: the ID is wrong, the connection was removed, or it belongs to another account.

insurance.connection.credentials_rejected

Returned as the result of Test connection: the provider did not accept the credentials you entered for the connection. Check the credentials your provider gave you for the connection's environment. See Testing › Test connection.

insurance.traffic.not_found

The insurance request record to be opened in the panel was not found: the ID is wrong or the record belongs to another account.

Checkout Form

These codes are returned by the Checkout Form's insurance requests and by an insured payment submission. The form handles them itself and offers the buyer options; you do not need to do anything. You can refer to these descriptions when reviewing your payment records and buyer complaints. What the buyer sees: Behavior Rules.

payment.insurance.* codes are returned only if the buyer selected insurance. All of them are returned before the payment attempt: the payment attempt does not start and no money moves. details.canContinueWithoutInsurance: true shows that the buyer can continue the payment without insurance.

payment.insurance.unavailable

The insurance selection could not be verified at that moment (details.retryable: true). The buyer can retry or continue without insurance.

payment.insurance.selection_rejected

The insurance selection cannot be used in this payment; for example, the quote expired or the selection was removed. The insurance code of the reason is in details.insuranceCode (e.g. insurance.quote.expired, insurance.quote.stale, insurance.selection.inactive). The buyer can get a new quote or continue without insurance.

payment.insurance.not_applicable

Insurance cannot be added to this payment. The reason is in details.reason:

The buyer can continue the payment without insurance.

payment.insurance.installment_not_supported

A payment with insurance can only be made in a single installment. The buyer can pay in a single installment or continue without insurance.

insurance.selection.not_found

The insurance selection was not found or does not belong to this payment.

insurance.selection.locked

The payment was submitted, so the insurance selection can no longer be changed or removed.

insurance.selection.inactive

The insurance selection is no longer valid: the buyer removed it, made a new selection, or the selection expired. The buyer can get a new quote or continue without insurance.

insurance.checkout.session_required

An insurance request was made without a Checkout Form session. These endpoints are called only by the Lunixi payment form.

insurance.checkout.session_invalid

The Checkout Form session is invalid or has expired. The buyer needs to open the payment form again.

General

insurance.dependency.unavailable

The operation cannot be completed right now (details.retryable: true). There is nothing to fix in your request. Retry after a while with the same request and the same Idempotency-Key.

insurance.internal.integrity

The request could not be completed on the server side; there is nothing to fix in your request. Retry with exponential backoff. If the problem persists, contact support with the requestId from the response.

insurance.auth.scope_missing

The request does not carry the permission required for this insurance operation. There is no field to fix in your request. If the problem persists, contact support with the requestId from the response.

insurance.auth.caller_not_allowed

This insurance operation cannot be performed for this caller. There is no field to fix in your request. If the problem persists, contact support with the requestId from the response.

Common codes

The following platform codes may also be returned by the insurance endpoints. Their meaning and solutions are on the shared pages:

Related

• Webhook Events: events that carry errorCode
• Flows › Responses and errors: error rules of the API path
• Concepts and Statuses: status axes