Idempotency and Retries

Idempotency-Key header

Include an Idempotency-Key header on every POST request. This prevents duplicate submissions, so retrying with the same key and body is safe.

POST /v1/submissions
Authorization: Bearer <your-api-key>
Idempotency-Key: <unique-key-per-submission>
x-correlation-id: <request-correlation-id>
Content-Type: application/json

Behavior

Scenario	Response
First request with a given key	`202 Accepted` — submission created, `submissionId` returned
Retry with same key and same body	`202 Accepted` — original `submissionId` returned (no duplicate created)
Same key with different body	`409 Conflict` — key collision detected

The idempotency window is 24 hours. After 24 hours, a key may be reused for a different submission.

Key generation

Use a sufficiently unique string — a UUID v4 is recommended:

Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000

Do not reuse keys across different submissions.

Retry strategy

When a network error or 5xx response occurs, you may safely retry with the same Idempotency-Key. The platform deduplicates on the server side. Recommended exponential back-off:

Attempt	Wait before retry
1st retry	1 second
2nd retry	2 seconds
3rd retry	4 seconds
4th retry	8 seconds

Stop retrying after a 4xx response — these indicate a problem with the request itself, not a transient server issue.

Get Started

Input Data Guide

API Platform

Idempotency-Key header

Behavior

Key generation

Retry strategy

​Idempotency-Key header

​Behavior

​Key generation

​Retry strategy

Idempotency-Key header

Behavior

Key generation

Retry strategy