Send an Idempotency-Key
POST /v1/candidates, POST /v1/invitations and POST /v1/invitations/{id}/resend accept an Idempotency-Key header: any unique string up to 200 characters, such as a UUID you generate per operation. Keep it for the retries of that one operation.
What a retry gets
| Retry with the same key | Response |
|---|---|
| and the same body, after the first request succeeded | The first response again; nothing new is created |
| and the same body, while the first is still running | 409 A request with this Idempotency-Key is already in progress |
| and a different body | 422 Idempotency-Key was used with a different request body |
after the first request was refused (a 4xx such as 400, 404 or 409) | Runs again: refusals aren't stored |
after a 5xx or a timeout | 409 for up to 60 seconds, then it runs again. A candidate or an invitation the first request already created comes back instead of a second one (or a 409) |
- 24 hours. A key is remembered for 24 hours, per company: a retry sent with another of your API keys (after a rotation, say) gets the same answer. After that the same key starts a new request. Use a new key for each new operation.
- Without a key a POST runs every time. A second candidate with the same email is still refused (
409), but a second invitation would be created, and a second resend would send another link.