Skip to main content
The YuvexPay API supports idempotency keys to prevent duplicate operations when retrying failed requests.

​
How it works

Include an X-Idempotency-Key header with a unique string on any POST request that creates a resource:
If you send the same request with the same idempotency key, the API returns the original response instead of creating a duplicate.

​
Which endpoints require it

“Optional” means the header is honoured when you send it — replay, payload check and all — but omitting it is not rejected, and the request then executes with no idempotency protection at all. Send one anyway.

​
Rules

  • Maximum length: 100 characters.
  • TTL: Idempotency keys are valid for 24 hours.
  • Scope: Keys are scoped per company and environment. The same key can be used in sandbox and production without colliding — they’re separate keyspaces.
  • Payload check: If you reuse a key with a different request body, the API returns a 409 Conflict with error code IDEMPOTENCY_PAYLOAD_MISMATCH. This holds for the whole 24h window and for concurrent requests, not only for retries that arrive shortly after the first one.
  • Concurrent requests: If a request with the same body and key is already being processed, the API returns a 409 Conflict with error code IDEMPOTENCY_CONFLICT. A concurrent request with a different body gets IDEMPOTENCY_PAYLOAD_MISMATCH instead.
  • Replay: Once a request completes successfully (2xx), subsequent retries with the same key return the original status code and body for the remainder of the 24h window.
Only successful (2xx) responses are stored. Error responses — both client errors (4xx) and server errors (5xx) — are not stored, so retrying with the same key after an error executes the request again. The key stays safe for retries.

​
Generating keys

Use a value that uniquely identifies the business operation, not just a random string:
Append a version suffix (e.g., -v1, -v2) to the key if you need to intentionally retry with different parameters.