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

# Idempotent requests

> Use idempotency keys to safely retry API requests without duplicating operations

The Hyperline API supports idempotency, allowing you to safely retry requests without accidentally performing the same operation twice. This is especially useful when a network error or timeout prevents you from knowing whether a request succeeded.

## How it works

Pass a unique `Idempotency-Key` header with any mutating request (`POST`, `PUT`, `PATCH`). If the request succeeds, Hyperline caches the response for **24 hours**. Any subsequent request with the same key returns the cached response instead of re-executing the operation.

```
POST /v1/invoices
Idempotency-Key: a8098c1a-f86e-11da-bd1a-00112444be1e
```

## Generating idempotency keys

Use a V4 UUID or any sufficiently random string (at least 16 characters). The key must be unique per **operation intent** — generate a new key for each distinct operation.

```javascript theme={null}
const { randomUUID } = require("crypto");

const response = await fetch("https://api.hyperline.co/v1/invoices", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${apiKey}`,
    "Idempotency-Key": randomUUID(),
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ customer_id: "cus_123", ... }),
});
```

## Behavior

| Scenario                                        | Result                                        |
| ----------------------------------------------- | --------------------------------------------- |
| First request with a key                        | Executes normally, caches response            |
| Retry with same key and same body               | Returns cached response (no re-execution)     |
| Request with same key but different body or URL | Returns `417 Expectation Failed`              |
| Concurrent requests with the same key           | Returns `409 Conflict` for the second request |

## Error responses

**409 Conflict - Request in progress**

A request with the same idempotency key is currently being processed. Wait for the original request to complete before retrying.

**417 Expectation Failed - Intent mismatch**

A completed request exists for this key, but the new request has a different method, URL, or body. This usually means you accidentally reused a key for a different operation. Generate a new key for the new request.

## Best practices

* **Generate keys client-side** before sending the request, so retries reuse the same key.
* **One key per operation** — do not reuse a key for logically different requests.
* **Retry on network errors** — if a request times out, retry with the same key. The operation will not be duplicated.
* **Do not retry on 4xx errors** (except 409/429) — these indicate a problem with your request that retrying won't fix.

## Supported endpoints

Idempotency keys are accepted on all mutating endpoints (`POST`, `PUT`, `PATCH`). They are ignored on `GET` requests since those are already safe to retry.