Idempotency

PublicSquare supports idempotency to guarantee multiple retries of the same request do not unintentionally perform the same operation more than once.

Our API endpoints accept a client-provided Idempotency Key if sent with the IDEMPOTENCY-KEY HTTP header within POST and PUT methods.

If an Idempotency Key is not provided by the client, retrying the same request might result in unwanted behavior.

The Idempotency Key must be a unique value generated by the client which is used by the PublicSquare API to identify subsequent requests belong to an original request. The Idempotency Key generation is up to the client, but we strongly recommend using a unique identifier such as UUID to avoid collisions.

When the first request comes in, its response status code and body is saved. Whenever a subsequent request comes in with the same Idempotency Key, the previous stored result will be returned if it succeeded. If the first request failed, the result is not stored and a subsequent request with the same Idempotency Key is processed as a new request. If any subsequent request comes in while the first is still processing, a 409 status code is returned.

If an Idempotency Key is provided for a GET or DELETE request, it is ignored and idempotency logic is not invoked, since these HTTP verbs are idempotent by definition.

All idempotency keys and their respective results are deleted after 24 hours. Therefore, if an Idempotency Key is reused after 24 hours, it will be handled as a new request.

Example

curl "https://api.publicsquare.com" \
-H "X-API-KEY: <API_KEY>" \
-H "IDEMPOTENCY-KEY: aa5d3379-6385-4ef4-9fdb-ca1341572153"