Idempotent requests

The Gigs API supports idempotency, so you can safely retry a request after a network error or timeout without performing the same operation twice. To make a request idempotent, include an Idempotency-Key header when creating or updating resources.

curl --url "https://api.gigs.com/projects/${GIGS_PROJECT}/users" \
  --header "Idempotency-Key: some-unique-generated-value" \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer ${GIGS_TOKEN}" \
  --data '{"email": "art.vandelay@example.com"}'

Idempotency keys

Idempotency keys are unique, client-generated strings of up to 255 characters. Each key identifies a single operation, such as creating one user or paying one invoice.

Generate a new key for every operation you want to perform. A random value with enough entropy to avoid collisions, such as a UUIDv4, is a good default. Avoid using sensitive data like email addresses in the key.

If an operation might be retried from a different context, such as another service or a restarted process that no longer has the original random value, derive the key from the operation itself instead. For example, use pay-inv_0SNlurA049MEWV1QTRqvd18YuG25 when paying that invoice.

Response behavior

Idempotency works by storing the status code and body of the first successful request for a given key. Subsequent requests with the same key return the same result for up to 24 hours. Only successful requests (HTTP codes lower than 400) are stored, so failed requests can be retried with the same key. For 500 errors, while we strive to keep internal failures free of side effects, we cannot always guarantee safe retries in the case of a potentially unknown error.

When a request returns a stored result instead of being processed again, Gigs includes an Idempotent-Replayed: true header in the response. Use it to tell a replay apart from a fresh execution, for example to confirm which of several retries actually performed the operation.

If you reuse a key while the original request is still being processed, Gigs returns a 409 conflict error. If you reuse a key with a different request body, Gigs returns a 422 invalid error, since a key must always map to the same operation.

Supported methods

All POST and DELETE requests accept idempotency keys. There is no need to send idempotency keys for GET, PUT, or PATCH requests as these are idempotent by definition. Sending a key with such a request has no effect, but is not an error.