Safely retry job-creation requests without creating (and paying for) a duplicate job.
POST https://api.versium.com/v2/jobs accepts an optional Idempotency-Key header. Use it to safely retry a job-creation request after a timeout, dropped connection or 5xx error without creating, and being charged for, a second job.
TheIdempotency-Keyheader is only supported onPOST /v2/jobs. Other endpoints ignore it.
How to use it
Generate a unique key, such as a UUID, once per job you mean to create, and send it in the Idempotency-Key header. On every retry of that request, send the same key and the same request parameters.
curl -X POST "https://api.versium.com/v2/jobs?operation=b2cContactAppend&sub_jobs[]=b2cEmailAppend&input_list_id=<list-id>&match_type=indiv" \
-H "x-versium-api-key: $API_KEY" \
-H "Idempotency-Key: 3f6c1a2e-8b4d-4e1f-9a7c-2d5e6f708192"The header is optional. If you leave it out, or send it empty, the endpoint behaves exactly as before.
Responses
| Situation | Response |
|---|---|
| First request with this key | 201: the job is created as normal. |
| Retry with the same key and the same parameters | 200: the original job is returned. Nothing new is created, validated or charged. |
| Same key, different parameters | 422: "This Idempotency-Key was already used with a different request body." |
| Same key, but the original job has since been deleted | 409: "The job created with this Idempotency-Key has been deleted." |
| Key is invalid (over 255 characters, not UTF-8, or ends in whitespace) | 422: validation error. |
Things to know
- Keys never expire. Once a key has created a job, it stays tied to that job permanently. Don't reuse a key for a different job.
- Keys are scoped to your user account, not to the individual API key. All API keys on the same account share one key space.
- A key is only used up when a job is actually created. If the first attempt failed validation, you can fix the request and retry with the same key.
- "Same parameters" ignores key order in a JSON body, but any change to a value counts as a different request.
- Simultaneous requests with the same key are safe: one creates the job and the others get that job back.
- A 200 replay returns the job's current state, so its status may have moved on since it was created.