Concepts
Idempotency
Retry safely without duplicate resources
Reference
Create operations accept an idempotency_key. Repeating the same request with the same key returns the original resource. Reusing the key with a different body returns an idempotency mismatch error.
Usage
Use a stable key from your order, job, or payout identifier.
curl -X POST https://api.halfin.xyz/api/v1/invoices \
-H "Content-Type: application/json" \
-H "X-API-Key: $HALFIN_API_KEY" \
-d '{"currency":"BTC","amount":"0.01000000","idempotency_key":"order-0001"}'import { createHalfin, createInvoice } from '@halfin/sdk-merchant';
const client = createHalfin({ apiKey: process.env.HALFIN_API_KEY });
await createInvoice({
client,
body: { currency: 'BTC', amount: '0.01000000', idempotency_key: 'order-0001' },
});# Python SDK coming soon. Use the cURL example for now.Pitfalls
- Do not generate a new idempotency key for every retry.
- Do not reuse one key across unrelated orders.
Troubleshooting
Idempotency key mismatch means the original request body and retry body differ. Reuse the original body or start a new operation with a new key.