Skip to main content
The 8bitedge API supports idempotent POST requests via the Idempotency-Key request header. When you attach a unique key to a request, the server stores the response. If you send the same key again with the same payload — for example after a network timeout left you unsure whether your original request succeeded — the server replays the original response byte-for-byte rather than processing the request a second time. This lets you retry safely without risk of double-counting, duplicate batch submissions, or other unwanted side-effects.

​
How it works

  • Generate a UUID per logical operation and attach it as the Idempotency-Key header on your POST or batch request.
  • A repeat with the same key and the same payload returns the stored response with an Idempotency-Replayed: true response header, confirming that no new work was performed.
  • Stored responses expire after 24 hours. After that window, submitting the same key is treated as a fresh request.
  • Idempotency applies to POST and batch requests only. GET requests are naturally safe to retry without a key.

​
Step-by-step example

1

Generate a UUID for the operation

Create a UUID v4 to use as your idempotency key. On most Unix systems you can use uuidgen:
Store this key alongside your operation record so you can replay it if something goes wrong later.
2

Send the initial request with the key

Attach the UUID as the Idempotency-Key header on your POST request:
The API processes the request normally and stores the response keyed to your UUID.
3

Retry on network error

If the request fails mid-flight — a timeout, dropped connection, or any other network error — you can safely retry using the exact same key and the exact same payload:
The API returns the original response without executing the operation a second time.
4

Verify the Idempotency-Replayed header

When the API detects a matching key + payload and serves a cached response, it sets Idempotency-Replayed: true in the response headers. Confirm this in your retry logic to be sure you received a replayed result rather than a fresh one:
If this header is absent, the request was processed fresh — either the key was new or the cached response had expired.

​
Error cases

If you receive a 409 idempotency_conflict, the original request is still being processed. Wait briefly and retry — the stored response will be available once it completes. If you receive a 422 idempotency_key_reuse, you have submitted a key that was previously used with a different request body. Generate a new UUID for the new operation; never repurpose a key.

​
Best practices

  • Use a UUID v4 per logical operation. UUIDs are statistically unique and inexpensive to generate. Create a fresh one for each distinct operation — not per retry.
  • Never reuse a key with different payloads. Each key is bound to the payload it was first submitted with. Sending a different body with the same key will always return 422 idempotency_key_reuse.
  • If you get a 409, wait briefly and retry. A conflict means your original request is still being processed. A short wait (a few seconds) is usually enough for the result to be stored.
Persist your idempotency key in your own database alongside the operation it represents — before you send the request. If your process crashes mid-flight, you can look up the key and replay the exact same request to recover safely, without having to guess whether the original request succeeded.