Error Types

Error type and management

API Errors

(Stated in headers): see the status code reference, global environment based Basic approach: “Does the API respond with a 20X response?” Useful for: - General API function - Confirmation of actions - Basic operation validation

Example of use: - Was a Create Offer request received? - Was a Confirm Offer request received? - Was there any full failures

Logic Errors

Logic errors are present in API response body, are case by case, and policy based. They are often the indicator of a problem with the Offer creation or confirmation, and may represent a partial booking failure. Always look for the errors array. Basic approach: “Does the request contain any content concerns, or logical failures?” Useful for: - Calculation issues - Confirmation over various state actions (does a booking match an Offer expectation) - In depth rule validation Example of use: - Was a create offer request valid? - Was a confirm offer request complete, were there any partial failures?

Logic error management:

1. All products in a create Offer or Confirm Offer request should be confirmed individually (not just package, or package status). An erroneous Offer will return a "null" response for the object. Example: Create Offer request

   Ensure there is no error field in response (flag if there is, may be a miss-offer or partial offer) Other Offer stage errors include "no policy available for these parameters" etc.
2. Confirm offer request items should be confirmed similarly Example, basic elements present, first quote id sent also present
3. Confirm Offer request shouldn't have errors, mismatched values, or null quote responses

In the below example, the Offer confirmation failed due to a validation error.

Understanding and monitoring for these response variations and errors will greatly reduce misaligned bookings and improve customer satisfaction.

Consistent error bodies with X-API-Error-Version

The response variations described above are the reason the Offers API supports an opt-in error shape. Sending the header X-API-Error-Version: v2 on Create Offer, Confirm Offer or Opt-out Offer returns every error response from those endpoints in one consistent structure, so both API errors and logic errors can be handled by a single code path instead of being matched case by case.

The v2 body always contains the same top-level fields: type, message, code, error_id, errors and metadata and errors is always an array whose entries identify the failing product and quote:

{
  "product_config_id": "8f2b41c9-6d7e-4a15-b3c8-1e9f0a2d5b76",
  "quote_id": "3c7d9e21-5b48-4f0a-8d16-2a9c4e7b0f53",
  "code": "booking_quote_failed",
  "details": ["Policyholder country is not eligible for this product"]
}

This makes the per-product checks described above straightforward: rather than inspecting each product object for a null quote or an ad-hoc error field, read errors[] and match on product_config_id and quote_id.

The header is opt-in and affects the shape of error bodies only. An omitted or unrecognised value never fails the request.

See Error Versioning for the full field reference, the error code list, worked examples and known limitations.