XCover uses conventional HTTP response codes to indicate the success or failure of API requests. Error codes ranging from 200 to 299 indicate successful operations. Error codes ranging from 400 to 499 represent various error codes. Errors that can be resolved programmatically will result in an error code that briefly explains the error type and the reason for failure. 5xx codes indicate an unexpected error within the XCover application. In the unlikely event of a 5xx error, our engineering team will automatically receive a notification and will fix the issue as fast as possible.

Error Handling

XCover uses conventional HTTP response codes to indicate the success or failure of an API request. Error codes ranging from 400 to 499 represent various error codes. Errors that can be resolved programmatically will result in an error code that briefly explains the type of error or reason for the error. In the unlikely event of a 5xx error, our engineering team will automatically receive a report and will fix any issue as fast as possible.

Note the below workflow for error handling:

XCover strongly recommends the following mechanisms for error handling:

Retry Mechanism

The request/response goes through various hops between Partners and XCover. These may include various networks and servers. If at any point, the request fails due to network issue for example (e.g. a timeout), Partners should try to resend the request at least twice to rule out any intermittent issue. For Asynchronous request situations, retries may be spaced comfortably, ideally 2-5 mins apart before sending out an alert for someone to manually check any issues. We recommend at least 5 second timeout for bookings, and setting it to 10 seconds or more should be more reliable and not be a problem for customers. If requests fail, they should be retried with exponential backoff. In case the booking creation failed 5 times, partners should flag and raise with Cover Genius. Similar logic should apply for cancellations.

API Errors

(Stated in headers): In API Guide, 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 quote request received? - Was a booking 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 booking or quote, 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 a quote expectation) - In depth rule validation Example of use: - Was a quote request valid? - Was a booking request complete, were there any partial failures?

Logic error management:

1. All quotes in a quote or booking request should be confirmed individually (not just package, or package status). An erroneous quote will return a "null" response for the object. Example:
2. Booking request items should be confirmed similarly Example, basic elements present, first quote id sent also present

In the below example, the booking was successful, but partially failed due to a component quote having a logic error.

1. A null quote component will result in a differing value for the policy bundle, even in a confirmed state.

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

An XCover Quote Package and individual Quotes within a Quote Package can transition between several different statuses. Below is a state diagram of these transitions and their conditions.

The XCover API operates with a set number of states that a quote can rest in. RECEIVED: Refers to an initial quote creation state - this is not a live policy, but may be booked from this state. CONFIRMED: A booked policy, this policy is confirmed as being paid for and activated. It may be active or expired. May be cancellable or modifiable, and can be claimed against. CANCELLED: A cancelled policy cannot be claimed against, or modified. DELETED: A rare status that depicts a removed quote/booking. PENDING_PAYMENT: Only relevant for quotes that are booked using the require_payment_confirmation flag during a create booking request (usually followed by the confirm booking request) end state if confirmed will be CONFIRMED. FAILED: A failed quote status. RENEWED: A state used to depict a renewed prior booked policy (for example after an annual renewal payment is confirmed).

QuoteStatus:
    RECEIVED
    CONFIRMED
    CANCELLED
    DELETED
    PENDING_PAYMENT
    FAILED
    RENEWED