Idempotency

Idempotency lets you safely retry API requests without the risk of duplicate operations. Include an Idempotency-Key header on a supported request and Titus will replay the original response on any retry using the same key.

How to send the header

We recommend a V4 UUID. Keys can be any unique printable ASCII string up to 255 characters.

Example

POST /v1/checkouts/abc-123/refunds HTTP/1.1
Host: api.gotitus.com
x-api-key: sk_live_abc123...
Idempotency-Key: 8a7f3b2c-4d5e-6f7a-8b9c-0d1e2f3a4b5c
Content-Type: application/json

{
  "amount": 500.00
}

Behavior on retry

When you retry a request with the same Idempotency-Key:

• The original response is replayed byte-for-byte — same status code, same body.

• The operation does not run again. No second refund, no second transfer.

• The response reflects state at the time of the original request. For async resources that change over time (e.g. refunds moving from pending to completed), use the corresponding GET endpoint if you need live status.

Error responses

Supported endpoints

The Idempotency-Key header is honored on the following endpoints. Other endpoints ignore it.