Retry a submission safely

A submission can fail on the way back to you: the connection drops after the API accepted the job, or a timeout fires while the response is in flight. Retry it as-is and you would start, and pay for, a second job. The idempotency-key header prevents that.

Send the header

Add idempotency-key to POST /jobs/{site} or POST /records/{site}. The value is yours to choose; the API only compares it.

curl -X POST https://api.urakimon.com/jobs/amazon \
  -H "x-api-key: $URAKIMON_API_KEY" \
  -H "content-type: application/json" \
  -H "idempotency-key: order-2026-09-23-0417" \
  -d '{"mode":"product","asins":["B0H1KXX5TL","B0F5HPCLGB","B0GG9BY46M"],"country":"US"}'

What a retry returns

A second request with the same key and the same idempotency-key returns the original job. No new job is created and nothing is charged twice.

• On POST /jobs/{site} the 202 carries the original job, with whatever status it has reached by then: queued, running or already final.
• On POST /records/{site} the response waits for that same job, if it is still running, and returns its records. The job id in the response is the original one.

The body is checked too. A retry with the SAME body returns the original job whatever its state, including failed and cancelled. The same idempotency-key sent with a DIFFERENT body answers 422 with this Idempotency-Key was already used with a different request; a key may only be reused to retry the SAME request — the original job is untouched. Never reuse a value for a different request; to run the same request again, send a new value.

Scope

Values are remembered per API key. Two of your keys can use the same value without meeting each other's jobs, and another account can never reach yours. Within one key the value is global, not per source: the same value sent to a second source returns the job from the first.

How long it is remembered

A value is remembered for as long as its job is kept. A finished job is removed 24 hours after it settles, or earlier once the key holds more than 1,000 finished jobs, oldest first. After that, the same value starts a new job. A service restart does not forget values: they are rebuilt from the stored jobs.

Choosing a value

Use something that is unique per intended submission and that you can regenerate on a retry: your own order or task id, or a UUID you store before sending. Keep it under 200 characters, the maximum the API reference lists for the header. Timestamps alone are a poor choice when two workers can submit in the same second.

Next step

Read Errors for the status codes a retry can meet, and which of them are safe to retry at all.