Idempotency Keys - Safe Retries for Write Requests

Network timeouts, client crashes, and rate-limit retries can leave you unsure whether a write request actually completed. Retrying blindly risks creating duplicate clients, transactions, alerts, or cases. Idempotency keys let you retry the same write request safely: Corsa processes it once and replays the original response on any retry within the retention window. The feature is fully backward compatible. Requests without an idempotency key behave exactly as they do today.

Idempotency keys are distinct from referenceId. See Idempotency keys vs. referenceId below.

How It Works

Send an Idempotency-Key request header on a write request. Corsa scopes the key to your platform and the specific request, so one customer’s key can never affect another, and the same key used for a different request is rejected.

First request with a new key is processed normally, and its result is stored.
A retry with the same key and the same request replays the stored response — with no duplicate side effects — and includes the Idempotent-Replayed: true response header.
A retry after a server error (5xx) is not replayed; Corsa attempts to process the request again.

Idempotency keys are currently supported on resource-creating POST requests. Sending the header on other verbs is accepted but has no effect.

Sending an Idempotency Key

Generate a unique string per intended write operation — a UUID (v4) is recommended — and reuse that same value on every retry of that operation.

curl -X POST "https://api.corsa.finance/v1/clients/individual" \
  -H "Authorization: Bearer <API_TOKEN>:<API_SECRET>" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 9f8b2c1e-6a2d-4f3b-9c1a-2e5d7f0a1b3c" \
  -d '{ "referenceId": "cust-001", "firstName": "Ada", "lastName": "Lovelace" }'

import { randomUUID } from 'node:crypto';
import { CorsaClient } from '@corsa-labs/sdk';

// One key per intended operation. Reuse it on every retry of THIS create.
const idempotencyKey = randomUUID();

const client = new CorsaClient({
  BASE: 'https://api.corsa.finance',
  HEADERS: {
    Authorization: `Bearer ${process.env.API_TOKEN}:${process.env.API_SECRET}`,
    'Idempotency-Key': idempotencyKey,
  },
});

const created = await client.clients.createIndividualClient({
  referenceId: 'cust-001',
  firstName: 'Ada',
  lastName: 'Lovelace',
});

import os
import uuid

from corsa_sdk import CorsaClient

# One key per intended operation. Reuse it on every retry of THIS create.
idempotency_key = str(uuid.uuid4())

client = CorsaClient(
    base_url="https://api.corsa.finance",
    token=f"{os.environ['API_TOKEN']}:{os.environ['API_SECRET']}",
    headers={"Idempotency-Key": idempotency_key},
)

A single client-wide header sends the same key on every request. That is only correct when the client issues one write. For most integrations, set the Idempotency-Key per request so each operation gets its own key.

Key Requirements

Requirement	Value
Header name	`Idempotency-Key`
Recommended format	Unique string per operation, e.g. a UUID
Maximum length	255 characters
Scope	Per platform + request path + key
Retention	24 hours after completion

Recognizing a Replayed Response

When Corsa replays a stored response, the body and status code are identical to the original, and the response carries an extra header:

HTTP/1.1 201 Created
Idempotent-Replayed: true
Content-Type: application/json

Check for Idempotent-Replayed: true when you need to distinguish a fresh write from a replayed one — for example, when reconciling logs after a retry storm.

Handling Conflicts

A reused key that does not match the original completed request returns 409 Conflict. There are two cases:

Scenario	Status	Meaning	What to do
Same key, different request payload	`409 Conflict`	The key was already used for a different request.	Use a new key for the new operation. Never reuse a key across different writes.
Same key while the original is still processing	`409 Conflict`	Your first request is in flight.	Wait, then retry with the same key. The in-progress lock clears after 60 seconds.

Retry After a Timeout

The core use case: your request times out and you do not know whether it succeeded. Retry with the same key.

If the first request completed, you get the original response back with Idempotent-Replayed: true — no duplicate created.
If the first request is still processing, you get 409 Conflict with an in-progress message; wait and retry with the same key.
If the first request failed with a 5xx, the retry is processed as a new attempt.

import { randomUUID } from 'node:crypto';
import { CorsaClient, ApiError } from '@corsa-labs/sdk';

const idempotencyKey = randomUUID();

async function createWithRetry(attempt = 0): Promise<unknown> {
  const client = new CorsaClient({
    BASE: 'https://api.corsa.finance',
    HEADERS: {
      Authorization: `Bearer ${process.env.API_TOKEN}:${process.env.API_SECRET}`,
      'Idempotency-Key': idempotencyKey, // same key on every retry
    },
  });

  try {
    return await client.clients.createIndividualClient({
      referenceId: 'cust-001',
      firstName: 'Ada',
      lastName: 'Lovelace',
    });
  } catch (err) {
    // 409 while the original is still processing: back off and retry the SAME key.
    if (err instanceof ApiError && err.status === 409 && attempt < 5) {
      await new Promise((r) => setTimeout(r, 2 ** attempt * 500));
      return createWithRetry(attempt + 1);
    }
    throw err;
  }
}

import os
import time
import uuid

from corsa_sdk import CorsaClient
from corsa_sdk.exceptions import ApiError

idempotency_key = str(uuid.uuid4())


def create_with_retry(max_attempts: int = 5):
    client = CorsaClient(
        base_url="https://api.corsa.finance",
        token=f"{os.environ['API_TOKEN']}:{os.environ['API_SECRET']}",
        headers={"Idempotency-Key": idempotency_key},  # same key on every retry
    )

    for attempt in range(max_attempts):
        try:
            return client.clients.create_individual_client(
                reference_id="cust-001",
                first_name="Ada",
                last_name="Lovelace",
            )
        except ApiError as err:
            # 409 while the original is still processing: back off, retry SAME key.
            if err.status == 409 and attempt < max_attempts - 1:
                time.sleep(2 ** attempt * 0.5)
                continue
            raise

Retention and Expiry

State	Retained for
Completed request (success or customer `4xx`)	24 hours
In-progress lock	60 seconds
Server error (`5xx`)	Not stored

After 24 hours, Corsa may treat the same key as a brand-new request. If you need retry safety beyond that window, generate a fresh key and treat the operation as new.

Idempotency Keys vs. `referenceId`

These solve different problems and are often used together.

	`Idempotency-Key`	`referenceId`
Purpose	Retry safety for a single API call	Your source-system identifier for an entity
Lifetime	24-hour retry window	Permanent mapping
Uniqueness	Per intended operation (e.g. a UUID)	Per entity in your system
On reuse	Replays the original response, or `409` if the request differs	Enables upsert / entity mapping (endpoint-dependent)
Scope	Any supported write request	Entities that support `referenceId`

Use an Idempotency-Key to make a retry safe. Use referenceId to map a Corsa entity back to a record in your system. During imports and backfills, set both: referenceId identifies the entity, and a per-row Idempotency-Key makes each write retry-safe.

Error Reference

Scenario	Status	Behavior
First request with a new key	Original endpoint status	Processed normally; result stored.
Same key, same completed request	Original endpoint status	Original status/body returned with `Idempotent-Replayed: true`.
Same key, different request	`409 Conflict`	Rejected with a key-conflict message; no side effect.
Same key while original is processing	`409 Conflict`	Rejected with an in-progress message; retry later with the same key.
Key longer than 255 characters	`400 Bad Request`	Rejected before processing.
Original request returned `5xx`	`5xx`	Not cached; a retry is processed again.
Same key after 24 hours	Original endpoint status	Treated as a new request.

API

Webhooks

AI Skills

Javascript

Python

HYOK

Idempotency Keys - Safe Retries for Write Requests

How It Works

Sending an Idempotency Key

Key Requirements

Recognizing a Replayed Response

Handling Conflicts

Retry After a Timeout

Retention and Expiry

Idempotency Keys vs. `referenceId`

Error Reference

​How It Works

​Sending an Idempotency Key

​Key Requirements

​Recognizing a Replayed Response

​Handling Conflicts

​Retry After a Timeout

​Retention and Expiry

​Idempotency Keys vs. referenceId

​Error Reference

How It Works

Sending an Idempotency Key

Key Requirements

Recognizing a Replayed Response

Handling Conflicts

Retry After a Timeout

Retention and Expiry

Idempotency Keys vs. `referenceId`

Error Reference