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.
Status
Description
200 - OK
Everything worked as expected
201 - Created
The request has been fulfilled and has resulted in one or more new resources being created
400 - Bad Request
The request was not accepted, often due to the wrong format of the request
401 - Unauthorized
No valid API key was provided
404 - Not Found
The requested resource doesn't exist
409 - Conflict
The request conflicts with another request, perhaps due to the usage of the same idempotency key
422 - Unprocessable Entity
Validation failed or logical error
429 - Too Many Requests
Too many requests hit the API too quickly. We recommend an exponential back-off of your requests.
500, 502, 503, 504 - Server Errors
Something went wrong on XCover side
General error management
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.
Alert Mechanism
If, after the second try Partners fail to receive the expected response (received, confirmed etc), it is recommended to establish alert mechanisms that notify responsible teams of the failure.
Logging Mechanism
Irrespective of a correct or a failed request/response, it is highly recommended for Partners to log requests and responses all centrally. These assist investigation where besides direct issue itself, patterns may become visible, helping to identify overarching issues.
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).
Error type and management
(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 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:
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:
Booking request items should be confirmed similarly Example, basic elements present, first quote id sent also present
Booking request shouldn't have errors, mismatched values, or null quote responses
In the below example, the booking was successful, but partially failed due to a component quote having a logic error.
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.