Skip to content
Space Invoices Documentation

Idempotency

Idempotency ensures that retrying a request (e.g., due to network failures) won’t create duplicate resources. Space Invoices supports idempotency via the X-Request-Id header.

How It Works

  1. Send a unique ID with your request using the X-Request-Id header
  2. First request is processed normally, response is cached
  3. Duplicate requests with the same ID return the cached response immediately

The cached response includes the original HTTP status code and body.

Usage

Include a unique identifier in the X-Request-Id header:

Usage curltypescript
# title: Idempotency with cURL
curl -X POST https://eu.spaceinvoices.com/v1/entities/ent_123/invoices \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Idempotency-Key: order-12345" \
  -H "Content-Type: application/json" \
  -d '{__PROTECTED_3__: {__PROTECTED_4__: __PROTECTED_5__}, __PROTECTED_6__: [{__PROTECTED_7__: __PROTECTED_8__, __PROTECTED_9__: 100}]}'

If your request times out and you retry with the same X-Request-Id, you’ll get the original response—no duplicate invoice is created.

Response Header

Every response includes an X-Request-Id header:

  • If you provided one, it’s echoed back
  • If you didn’t, one is generated for you

You can use the returned ID to safely retry requests.

Best Practices

When to use idempotency keys:

  • Creating resources (invoices, customers, payments)
  • Any mutation that shouldn’t be duplicated

How to generate keys:

  • Use UUIDs: 550e8400-e29b-41d4-a716-446655440000
  • Or combine operation + entity: create_invoice_order_12345
  • Include a timestamp if needed: inv_create_1704067200_abc

Key scope:

  • Keys are scoped to your account—different accounts can use the same key
  • Keys persist indefinitely in request logs

SDK Usage

Pass the header via request options:

Usage sdktypescript
// title: Idempotency with SDK
const invoice = await sdk.invoices.create(
  {
    customer: { name: "Acme Corp" },
    items: [{ name: "Service", quantity: 1, price: 100 }],
  },
  { idempotencyKey: "order-12345" }
);

// Safe to retry - same invoice returned
const retry = await sdk.invoices.create(
  {
    customer: { name: "Acme Corp" },
    items: [{ name: "Service", quantity: 1, price: 100 }],
  },
  { idempotencyKey: "order-12345" }
);

console.log(invoice.id === retry.id); // true