Idempotency

Idempotency helps you safely retry an API request without performing the same operation more than once. It is useful when a request times out or a network error prevents you from knowing whether Stitch processed it.

To make a request idempotent, include an Idempotency-Key header. If you need to retry the request, send the same key and the exact same request again. Stitch will return the original response instead of processing the operation a second time.

Idempotency is available for authenticated requests to both the Stitch GraphQL and REST APIs. It is optional: requests without an Idempotency-Key are processed normally.

Creating an Idempotency Key

Create a new UUIDv4 key for each logical operation (i.e. a single request), such as 2f1f7f9d-ec9b-45e8-9c1e-65d69bca6d4e.

Idempotency keys are scoped to your Stitch client and retained for 24 hours from the first request. We recommend that you never reuse a key for a different operation, even after the 24-hour period has passed.

Store the key with your operation so that the same key is available if a retry is needed.

Sending an Idempotent Request

Include the key in the Idempotency-Key request header:

GraphQL

curl -X POST 'https://api.stitch.money/graphql' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: 2f1f7f9d-ec9b-45e8-9c1e-65d69bca6d4e' \
  -d '{"query":"mutation Example { ... }"}'

REST

curl -X POST 'https://api.stitch.money/v2/terminal-sessions' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: 2f1f7f9d-ec9b-45e8-9c1e-65d69bca6d4e' \
  -d '{
    "intent": {
      "charge": {
        "amount": 350.5,
        "currency": "ZAR"
      }
    },
    "terminal": "dGVybWluYWwvMmNiN2NhMTQtNGQwYi00ODg3LTk2MWItOTRmYWYzMzJkMGYw",
    "nonce": "9599a853-4333-4359-89de-658bfc86773a"
  }'

Keep retries identical

The retried request must be absolutely identical to the initial request (including the HTTP method, path, query parameters, and request body). Changing the request while using the same idempotency key results in an IDEMPOTENCY_KEY_ALREADY_USED error.

Idempotency works alongside a resource's nonce. A nonce is a client-defined reference that prevents duplicate resource creation. Retrying resource creation with the same nonce results in a conflict error, even when a different idempotency key is used. Use the same nonce and idempotency key when retrying a request.

Understanding the Response

When idempotency is applied, Stitch includes an Idempotency-Replayed response header:

Value	Meaning
false	Stitch processed the request. This is the initial request, not a replay.
true	Stitch replayed the response. This indicates that the previous request was processed.

A replayed response has the same HTTP status, content type, and body as the original response.

Retrying Requests

Follow these recommendations when retrying an operation:

1. Generate and store the idempotency key before sending the first request.
2. If a timeout, connection failure, or other ambiguous transport error occurs, retry with the same key and exact request.
3. Use exponential backoff with jitter between retries.
4. Do not generate a new key because the original response was lost. A new key represents a new operation and could cause duplicate processing.
5. Stop retrying after receiving a definitive response, unless its error guidance says that it is safe to continue.

Idempotency records expire 24 hours after the first request. Do not assume that retries made after this period will replay the original response. Instead, check the operation's current status before deciding whether to submit another request.

Idempotency Errors

The following errors can occur before Stitch processes a request:

Error code	REST status	Cause	Recommended handling
IDEMPOTENCY_REQUEST_IN_PROGRESS	409	Another request with the same key and request is still running.	Wait and retry the exact same request with the same key. Use exponential backoff with jitter.
IDEMPOTENCY_KEY_ALREADY_USED	409	The key was already used for a different request.	Do not retry this request with that key. Check for accidental request changes or incorrect key reuse.

GraphQL

The GraphQL API returns an HTTP 200 response and includes the error code in errors[].extensions.code. For example:

{
  "data": null,
  "errors": [
    {
      "message": "This idempotency key has already been used for a different request.",
      "extensions": {
        "code": "IDEMPOTENCY_KEY_ALREADY_USED"
      }
    }
  ]
}

REST

REST APIs return the error code in the response body. For example:

{
  "code": "IDEMPOTENCY_KEY_ALREADY_USED",
  "title": "Idempotency Key Already Used",
  "detail": "This idempotency key has already been used for a different request."
}