Skip to main content
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. 
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

ScenarioResult
First request with a keyExecutes normally, caches response
Retry with same key and same bodyReturns cached response (no re-execution)
Request with same key but different body or URLReturns 417 Expectation Failed
Concurrent requests with the same keyReturns 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.