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
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.
- Concurrent requests: If a request with the same key is already being processed, the API returns a
409 Conflict with error code IDEMPOTENCY_CONFLICT.
- 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.
