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:
KEY=$(uuidgen)
echo $KEY
# e.g. 4f8b2c3d-1a2b-4e5f-9c0d-7e8f1a2b3c4d
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:
KEY=$(uuidgen)
curl -s -X POST "https://api.8bitedge.com/api/v1/signals/batch" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $KEY" \
  -d '{ "requests": [ { "id": 1 } ] }' | jq
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:
# Safe to retry on a network error — same key + body replays the stored result:
curl -s -D - -X POST "https://api.8bitedge.com/api/v1/signals/batch" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $KEY" \
  -d '{ "requests": [ { "id": 1 } ] }' \
  -o /dev/null | grep -i idempotency-replayed
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:
Idempotency-Replayed: true
If this header is absent, the request was processed fresh — either the key was new or the cached response had expired.

​
Error cases

StatuscodeWhen
409idempotency_conflictThe same key is still in flight — the original request has not yet finished processing
422idempotency_key_reuseThe same key was submitted with a different payload
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.