RasterNivoUsing the API
Retries and idempotency
Networks fail. If an upload times out, you can't tell whether it arrived. Idempotency keys make it safe to send it again: you won't create a second job or be charged twice.
Idempotency keys
POST /v1/conversions requires an Idempotency-Key header of 1 to 255 printable ASCII characters. Use a UUID, or something from your own system such as invoice-1042-page-images. Use a new key for each conversion you intend, and the same key when retrying the same one. Keys are remembered for 24 hours in your workspace.
| You send | You get |
|---|---|
| The same key, same file and same options | The original job again. No new job, no new charge. |
| The same key with a different file or options | 409 idempotency_key_reused |
| The same key while the first request is still running | 409 idempotency_in_progress with Retry-After |
When to retry
| Result | Retry? |
|---|---|
| Network error or timeout | Yes, with backoff and the same key |
429 | Yes, after the Retry-After time |
500, 503 | Yes, with backoff and the same key |
Any other 4xx | No. Fix the request first. |
A job that failed | Depends on error.code. Fix the cause and submit with a new key, because the old key returns the same failed job. |
Backing off
Wait longer after each failure and add some randomness, so that many clients don't all retry at once: for example about 1 second, then 2, 4, 8, up to about a minute, and stop after a few attempts.
Check a job's status at most once a second. For long jobs, wait longer between checks or use a webhook.