Error Versioning

Opting into the versioned error response shape

Error Versioning

Error responses from the Offers API can be returned in a consistent, versioned shape by sending the X-API-Error-Version header. This is opt-in: the header changes the shape of error response bodies only and has no effect on successful responses or on any business logic.

Without the header, the structure of an error body varies between endpoints and between failure modes, which makes error handling difficult to implement generically. Sending X-API-Error-Version: v2 guarantees a single shape with a fixed set of top-level fields on every error response, so a single error handler can parse all of them.

We recommend all new integrations send X-API-Error-Version: v2.

Supported endpoints

Endpoint	Method and path
Create Offer	POST /partners/{partner_id}/offers/
Confirm Offer	POST /partners/{partner_id}/offers/{offer_id}/confirm/
Opt-out Offer	POST /partners/{partner_id}/offers/{offer_id}/opt_out/

On these endpoints the header applies to every error response, that is, every response with a status code of 400 or above.

The v2 error shape

Every v2 error response body contains the following top-level fields.

Field	Type	Description
type	string	Broad error category: validation_error, invalid_request_error, auth_error or api_error.
message	string	Human-readable summary of the failure. Intended for logs and diagnostics, not for display to customers.
code	string	Machine-readable code for the failure as a whole. See Error codes.
error_id	string	Identifier for this failure, for use when raising a support request.
errors	array	Per-item detail of what failed. An empty array when the failure is not attributable to specific items. See below.
metadata	object	Supplementary context. An empty object when there is none.

The errors array

Each entry in errors is an object with these four fields:

Field	Type	Description
product_config_id	string | null	The product configuration the failed item belongs to. null when the failure is not specific to one product.
quote_id	string | null	The quote the failed item relates to. null when no quote had been created at the point of failure, or when the failure is request-level.
code	string	Machine-readable code for this specific item. See Error codes.
details	array	Array of strings describing this item's failure.

Examples

Create Offer, where every quote failed to price (422 Unprocessable Entity):

{
  "type": "validation_error",
  "message": "Offer could not be created due to quote generation errors",
  "code": "offer_quote_generation_failed",
  "error_id": "b9c1f0d2-3a4e-4c6b-9f21-7d8e5a0b1c34",
  "errors": [
    {
      "product_config_id": "8f2b41c9-6d7e-4a15-b3c8-1e9f0a2d5b76",
      "quote_id": "3c7d9e21-5b48-4f0a-8d16-2a9c4e7b0f53",
      "code": "offer_quote_pricing_error",
      "details": ["No rate available for the supplied parameters"]
    },
    {
      "product_config_id": "a41e9c72-8b05-4d63-9f18-6c2a7e0d4b95",
      "quote_id": null,
      "code": "quote_creation_failure",
      "details": ["Upstream pricing service unavailable"]
    }
  ],
  "metadata": {
    "selected_offer_id": "5d8a2f61-9c04-4e73-b1a8-3f6e7c0d9b42"
  }
}

Confirm Offer, where none of the requested quotes could be booked (422 Unprocessable Entity). Note that error_id is the Offer ID:

{
  "type": "validation_error",
  "message": "None of the requested quotes were successful.",
  "code": "booking_quotes_unsuccessful",
  "error_id": "5d8a2f61-9c04-4e73-b1a8-3f6e7c0d9b42",
  "errors": [
    {
      "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"]
    }
  ],
  "metadata": {}
}

A request-level validation failure, where the failure cannot be attributed to a product or quote. Note that message here is generic and that the field-keyed detail is preserved under metadata.field_errors:

{
  "type": "validation_error",
  "message": "An API error occurred.",
  "code": "offer_validation_request_invalid",
  "error_id": "7e4c1a80-2f39-4b6d-95e1-8a0c3d7b6f14",
  "errors": [
    {
      "product_config_id": null,
      "quote_id": null,
      "code": "offer_validation_request_invalid",
      "details": ["Quote does not exist"]
    }
  ],
  "metadata": {
    "field_errors": {
      "quotes": ["Quote does not exist"]
    }
  }
}

Error codes

Codes appear in the top-level code and in each errors[].code. Treat the list as open-ended: new codes may be added, so always handle an unrecognised code by falling back to the HTTP status.

Code	Typical status	Meaning
offer_partner_not_found	404	The partner in the request path does not exist.
offer_not_found_no_offers	404	No Offers are configured for this partner.
offer_no_products	404	The selected Offer has no products available.
offer_not_found_no_match_context	422	No Offer matches the supplied request context.
offer_quote_generation_failed	422	Package level: no quote in the Offer could be generated.
offer_quote_pricing_error	422	Item level: a quote was created but could not be priced.
quote_creation_failure	422	Item level: the quote could not be created at all.
offer_quote_multiple_per_product	422	More than one quote was produced for a product that permits one.
offer_validation_request_invalid	422	The request body failed validation.
offer_validation_schema_required	422	No schema was supplied and the partner has no default schema.
offer_validation_schema_invalid	422	The supplied schema identifier is not valid for this partner.
offer_schema_validation_failed	422	The request did not validate against the partner's Offer Schema.
offer_enrichment_failed	422	Enrichment of the request data failed.
expression_evaluation_failed	422	An Offer configuration expression could not be evaluated.
too_many_instances	422	The resolved quantity exceeds the permitted number of instances.
quantity_expression_invalid_output	422	A quantity expression returned an unusable value.
too_many_variants	422	The resolved variants exceed the permitted number.
variant_expression_invalid_output	422	A variant expression returned an unusable value.
variant_config_expression_failed	422	A variant configuration expression could not be evaluated.
variant_config_expression_invalid_output	422	A variant configuration expression returned an unusable value.
booking_quotes_unsuccessful	422	Package level: none of the requested quotes could be booked.
booking_quote_failed	422	Item level: the per-quote reason inside a booking_quotes_unsuccessful response.
booking_quote_not_found	404	A quote ID in the confirm request does not belong to this Offer.
offer_request_failed	any	Generic fallback where no more specific code applies.
offer_unexpected_error	500	Unexpected server-side failure.

Limitations

Two cases are not covered by the versioned shape and should be handled defensively:

1. Unhandled server errors. An unexpected failure that produces no structured API response rendered as a generic 500 is returned as-is and will not carry the v2 fields.

2. Partial successes. A response that carries a success payload alongside a non-2xx status is left unchanged, because its body is not an error body. Continue to inspect the errors field of the payload in these cases, as described in Error Types.