NuminaDevelopers
Dashboard
Idempotency

Idempotency

Send an Idempotency-Key header so a request retried after a timeout returns the first result instead of creating a second journal entry or invoice.

A network error does not tell you whether the server created the entry. Send an Idempotency-Key with the request, and you can retry it without risking a duplicate.

cURL
curl -X POST https://api.numina.app/v1/journal-entries \
  -H "Authorization: Bearer $NUMINA_API_KEY" \
  -H "Idempotency-Key: 5f8d2a3e-6c1b-4b7e-9a0f-2d4c6e8b1a3f" \
  -H "Content-Type: application/json" \
  -d @entry.json

Supported on Create journal entry, Create invoice and Send invoice by email.

How it behaves

  • Generate one key per logical request, such as a UUID, and reuse it only for retries of that request. Keys are 1 to 255 characters.
  • A retry with the same key and body returns the original status and body, with the header Idempotent-Replayed: true. Replays still count toward rate limits.
  • Keys belong to the company, shared by every key and app connected to it, and are remembered for 24 hours from the first request.
  • A failed request (4xx or 5xx) frees the key, so you can fix the body and try again with the same key.
  • The same key with a different body or on another endpoint returns 422 idempotency_key_reused. A retry while the first request is still running returns 409 idempotency_key_in_use; wait and retry. A request that never finished frees its key after 5 minutes.

Other writes

  • Booking a journal entry or an invoice is safe to repeat: one that is already booked comes back unchanged with 200.
  • POST /v1/attachments recognises a file the company already has and returns that document with 200 and duplicate: true.
  • Uploading to an entry that already has a document returns 409 attachment_exists, and adding files to a document that has some returns 409 attachment_not_empty.
  • POST /v1/contacts is not protected, so a retry can create a second contact. Search for it first.
  • POST /v1/products refuses a repeat only when its product_number is already in use.