Skip to main content
The network can fail after the API writes a resource and before the response reaches your system. In that case, your system does not know if the write happened. With the Idempotency-Key header, your system repeats the call, and the API writes the resource only once. The header is optional. It applies to every POST of the API and to PATCH /documents/{id} with a file. Send the header in each of these calls.

​
How to use it

  1. Create a unique value for each write. A UUID works.
  2. Keep the value with the write in your system.
  3. Send the value in the Idempotency-Key header of the call.
  4. If the response does not arrive, repeat the call with the same value and the same content.

​
What the API does with the value

The API compares each call with the first call that used the same value. The comparison uses the method, the path, the parameters, and the name and the content of each file. The order of the fields in the body does not change the comparison.

​
What to do with each error

​
Responses that the API keeps

The API keeps the success response (2xx) and the 409 and 422 errors of the resource. A repeated call returns that response as it came the first time. To correct a call that got 409 or 422, use a new value. The API does not keep the other responses, such as 400, 401, 402, 403, 404, 413, 429 and 5xx. It also does not keep the idempotency_key_in_use and idempotency_key_reused errors, or the 422 of a request outside the contract. See Errors. A repeated call without a kept response runs again.

​
Rules

  • The value has 1 to 255 characters. A longer value gets 400 with the code invalid_parameter.
  • PATCH /documents/{id} with fields ignores the value. The API runs each call with fields as a new call.
  • Each API key has its own values. Two API keys can use the same value without a conflict.
  • A repeated call that gets the kept response does not use a paid write. The call counts toward the limit of calls per minute.
  • The API keeps the response for 24 hours. After that period, the API can delete the response. A call with the same value then runs as a new call.