> For the complete documentation index, see [llms.txt](https://partner-docs.covergenius.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://partner-docs.covergenius.com/offers/guides/migrating-from-rentalcover/authentication-and-errors.md).

# Credentials, signing & errors

Replace the static RentalCover API key with signed requests, add idempotency keys and update your error handling.

RentalCover authenticates with a static `X_API_KEY` header. The Offers API signs every request with an HMAC signature, accepts idempotency keys on writes, and returns structured validation errors. Make these changes once, in your HTTP client, before you migrate any flow.

{% stepper %}
{% step %}

#### Sign every request

Ask your CSE for an API key and secret. One key and secret work for every XCover product, and you get one pair per environment.

{% tabs %}
{% tab title="Before: RentalCover" %}

```http
X_API_KEY: {your_api_key}
Content-Type: application/json
```

{% endtab %}

{% tab title="After: XCover Offers" %}
{% code overflow="wrap" %}

```http
Content-Type: application/json
Date: Tue, 13 Oct 2026 12:00:00 GMT
Authorization: Signature keyId="{api_key}",algorithm="hmac-sha512",signature="{signature}"
```

{% endcode %}
{% endtab %}
{% endtabs %}

To build the signature, compute an HMAC of the string `date: {Date header value}` with your secret, then Base64-encode and URL-encode the result. The [Authentication](https://partner-docs.covergenius.com/offers/api/authentication.md) page has ready-made examples in several languages.

{% hint style="warning" %}
Sign on your server and keep the secret out of client code and logs. Keep your server clock in sync, because the signature depends on the `Date` header.
{% endhint %}
{% endstep %}

{% step %}

#### Add idempotency keys

Send an `x-idempotency-key` header on these calls, using a unique value per operation:

* Confirm Offer, including a pending Confirm
* Finalise a pending booking
* Cancel and confirm cancellation
* Modify, quote for update and confirm update

Idempotency is supported on most write endpoints, but not on Create Offer (`POST /offers/`) or the opt-out endpoints (`POST /offers/{offer_id}/opt_out/` and `POST /quotes/{quote_id}/opt_out/`). These endpoints ignore the header. Repeating a Create Offer request creates a new offer each time. Repeating an opt-out returns `422`, because the quote is already opted out.

On supported endpoints, a request counts as a repeat only if the key, the endpoint and the request body all match the original. Then:

* If the original request succeeded, the API returns `409` with the original response body. **Treat `409` as success.**
* If the original request is still being processed, the API returns `423`. Wait briefly and retry with the same key.
* If the original request failed with a non-`2xx` response, nothing is stored. Retrying with the same key runs the request again.

See [Idempotency Keys](https://partner-docs.covergenius.com/offers/api/idempotency-keys.md).
{% endstep %}

{% step %}

#### Update error handling

Validation errors move from `400` to `422`. Send `X-API-Error-Version: v2` on every request to get the v2 error format on Create Offer, offer opt-out and Confirm Offer. Branch on the machine-readable `code`, not the message text. The booking endpoints (cancel, modify, Get Booking) return the standard error format.

{% tabs %}
{% tab title="Before: RentalCover" %}

```json
HTTP 400
{
  "errors": {
    "firstName": ["..."]
  }
}
```

{% endtab %}

{% tab title="After: XCover Offers (v2)" %}

```json
HTTP 422
{
  "type": "validation_error",
  "code": "offer_validation_request_invalid",
  "error_id": "00000000-0000-4000-8000-000000000000",
  "errors": [
    { "code": "offer_validation_request_invalid", "details": ["'a' is not of type 'boolean'"] }
  ],
  "metadata": {
    "field_errors": { "context.bundled": ["'a' is not of type 'boolean'"] }
  }
}
```

{% endtab %}
{% endtabs %}

| Status    | What to do                                                                          |
| --------- | ----------------------------------------------------------------------------------- |
| 2xx       | Success. Opt-out returns `204` with no body.                                        |
| 404       | Not found. Confirming an expired offer also returns `404`: create a new offer.      |
| 409       | Replay of a request already processed. Treat as success.                            |
| 423       | The same request is still being processed. Retry with the same idempotency key.     |
| 422       | Validation failed, or the booking status doesn't allow the action. Fix the request. |
| Other 4xx | Change the request before retrying.                                                 |
| 5xx       | Retry at least twice, 2 to 5 minutes apart, with the **same** idempotency key.      |

Log the `error_id` so Cover Genius support can trace the failure. See [Error Versioning](https://partner-docs.covergenius.com/offers/api/responses/error-versioning.md).
{% endstep %}
{% endstepper %}

## Data format changes

| Data                | Before: RentalCover              | After: XCover Offers                                                                                                             |
| ------------------- | -------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| Dates and times     | `2027-03-12 10:00:00`, no offset | RFC 3339 with the local offset: `2027-03-12T10:00:00+01:00`                                                                      |
| Money               | Mostly strings                   | Numbers, such as `52.51`. Never parse the `_formatted` strings                                                                   |
| Booking ID (INS)    | Two groups of 4: `XXXX-XXXX-INS` | Two groups of 5: `XXXXX-XXXXX-INS`, optionally with a region prefix such as `U-` or `I-`. Relax any regex or fixed-length column |
| Offer and quote IDs | —                                | UUIDs                                                                                                                            |
| Postcodes           | —                                | Strings. Send and store them as strings                                                                                          |

Countries (ISO 3166-1 alpha-2), currencies (ISO 4217) and languages (ISO 639-1) are unchanged. See [Data Formats](https://partner-docs.covergenius.com/offers/api/data-formats.md).

## See also

* [Authentication](https://partner-docs.covergenius.com/offers/api/authentication.md)
* [Idempotency Keys](https://partner-docs.covergenius.com/offers/api/idempotency-keys.md)
* [Error Management](https://partner-docs.covergenius.com/offers/api/responses/error-management.md)
* [Error Versioning](https://partner-docs.covergenius.com/offers/api/responses/error-versioning.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://partner-docs.covergenius.com/offers/guides/migrating-from-rentalcover/authentication-and-errors.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
