> ## Documentation Index
> Fetch the complete documentation index at: https://docs.salesbricks.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Idempotent Requests

To ensure idempotent requests, include the `X-SALESBRICKS-IDEMPOTENT-OPERATION-KEY` header in your requests to Salesbricks.

<Note>
  This key is crucial for identifying and de-duplicating specific requests, safeguarding against unintended duplication.
</Note>

## Header Key

The header key should be `X-SALESBRICKS-IDEMPOTENT-OPERATION-KEY`.

## Header Value

An idempotency key is a **unique-to-you** value generated by you, the client, which the server uses to identify **a specific request** and de-duplicate it from subsequent retries of the same request.

<Tip>
  How you create unique keys is up to you, but we suggest including UUIDs or other unique IDs as part of the value to avoid collisions.
</Tip>

Idempotency keys can be up to 255 characters long.

The key should be used to identify the request, not just the data being sent (as even failure requests are saved).

We recommend generating and storing a key per-request-to-Salesbricks (see example below).

## Handling of Duplicate Idempotency Keys

### Subsequent Requests with the same idempotency and same payload

Salesbricks saves the response of the first request made for any given idempotency key, regardless of whether it succeeded or failed.

Subsequent requests with the same key return the same result.

This means if you received an error response on a request made with an idempotency key, a following request using that same key will return that same error response.

This is true for any error response, including 500 errors, as long as the request actually made it to Salesbricks' servers.

### Subsequent Requests with the same idempotency key but a different payload

The idempotency system also compares incoming requests to the original request and errors, unless they're the same, to prevent accidental misuse.

If you send a request with the same key but a different payload, you will receive a status code `400` error in response.

### Duplicate Concurrent Requests with the same idempotency keys

If you send 2 requests with the same idempotency key to Salesbricks, the requests will be processed serially, and the one which is processed later will return a status code `409` to indicate a conflict.

## Example Implementation

Let's say you would like to report usage on an order tracked in Salesbricks. Let's also say you track the usage for the order internally using the timestamp at which the usage occurred.

One approach you could take is to create a table called `SalesbricksUsageReportingRequests` in your database, which could look something like:

| DB column name                              | Description                                                                                                      |
| ------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| **`salesbricks_idempotent_key` (pk, uuid)** | A **UUID** which is your idempotency key value, that you generate when you make the usage request to Salesbricks |
| **`internal_usage_id` (str)**               | The ID you use to identify usage internally in your system                                                       |
| **`created_at` (optional, timestamp)**      | Timestamp at which you make the request to Salesbricks, for debugging                                            |
| **`response_code` (optional, int)**         | Response code you received from Salesbricks, for debugging                                                       |
| **`response` (optional, jsonb str)**        | Response payload you received from Salesbricks, for debugging                                                    |

Then, when you report your usage, you:

<Steps>
  <Step>
    Create a row in `SalesbricksUsageReportingRequests` storing the `created_at` timestamp, `internal_usage_id` and `salesbricks_idempotent_key`.
  </Step>

  <Step>
    Make the request to Salesbricks, specifying the `salesbricks_idempotent_key` in the `X-SALESBRICKS-IDEMPOTENT-OPERATION-KEY` header.
  </Step>

  <Step>
    Save the response you get back in the `SalesbricksUsageReportingRequests` table.
  </Step>
</Steps>

If you got an error response such as a `400`, in which you sent an invalid request where the usage was not successfully reported, you can adjust the sending code to send the correct payload.

Then, retry the steps above, generating a new `salesbricks_idempotent_key` for the new request.