# Idempotency

The OffBlocks API supports API idempotency. This allows safe request retries (during the validity time window of the key) while only performing the requested action once.

For example, if there is a temporary connection issue, a request to create an account could be safely retried several times without creating multiple accounts.

{% hint style="info" %}
Always use a different idempotency key for different requests

You **must** use different idempotency keys for different requests. Reusing the same idempotency key will cause the subsequent requests to not be executed. Reuse of an idempotency key with a different payload, while the key is still valid, results in an error.
{% endhint %}

### Enabling Idempotency

To use idempotency, where required (this includes all modifying requests such as `POST`, `PUT`, `PATCH` and `DELETE`), add the `Idempotency-Key` header as shown in the following example endpoint. We expect a key in a format of UUID to be provided. This is automatically generated and populated for relevant requests in our Postman collection.

{% openapi src="/files/ZuFqAH96VVGgwQAJ2vzc" path="/customers" method="post" %}
[offblocks-api-spec\_master\_api.yaml](https://1545901005-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FTToCQFhAYRMgObGgbSjC%2Fuploads%2FV89o79d3urx40FHQswwW%2Foffblocks-api-spec_master_api.yaml?alt=media\&token=762e0468-4f4f-407e-9281-df4ee98be768)
{% endopenapi %}

### Scope and Validity

Each idempotency key has a duration of **1 hour**.

During the validity period, you can only send the same payload with the same idempotency key. If you do this, you receive an identical response.

If the payload is different, but the idempotency key is the same, you receive an error. The error is likely 422 or 409, explained below.

### Error Handling

These are some of the common errors associated with idempotency:

| Error code | Error type                           | Detail                                                                   | Solution                                                                                                                                                                                                                                                                                                               |
| ---------- | ------------------------------------ | ------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 400        | BadRequest                           | Invalid request signature.                                               | Include the `Idempotency-Key` header when making requests to endpoints where idempotency is mandatory.                                                                                                                                                                                                                 |
| 409        | Idempotency-Key Concurrency Conflict | The Idempotency-Key value is being used for a concurrent request.        | <p>You submit a new request with a different idempotency key.<br><br>This error occurs because another request with the same idempotency key is in flight.<br><br>If you wait until the request is no longer in flight and make the same request with the same idempotency key, you receive an identical response.</p> |
| 422        | Idempotency-Key Reuse                | The Idempotency-Key value has already been used for a different request. | <p>Make your request with a new idempotency key.<br><br>Technically, you could also wait for the validity period of the idempotency key to end after 1 hours.</p>                                                                                                                                                      |


---

# Agent Instructions: Querying This Documentation

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

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.offblocks.xyz/developer-guides/api-integration/idempotency.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.