Skip to main content
We support idempotent requests to help you retry safely without creating duplicates. This is especially important for actions like creating payments, modifying data, or submitting forms, where repeated requests could otherwise result in undesired side effects.

​
What Is Idempotency?

Idempotency ensures that performing the same request multiple times has the same effect as performing it once. If your client experiences a timeout or network error, you can retry the request using the same idempotency key, and we will ensure it is only processed once.

​
How It Works

To make an idempotent request, include a unique key in the header: Idempotency-Key: your-unique-idempotency-key We store the status code and response body of the first request associated with that key. Any subsequent request with the same key:
  • Returns the original result, regardless of success or failure
  • Prevents duplicate processing of resource creation or updates
  • Maintains data integrity across retries
This behavior applies even if the first request resulted in a 500 or other server error, ensuring consistency regardless of outcome.
Idempotency-Key in GET or DELETE requests is ignored.

​
Key Expiration

  • Idempotency keys are stored for 24 hours.
  • After expiration, reusing the same key is treated as a new request.
  • Keys are up to 255 characters long.

​
Response Headers

To help clients verify how an idempotent request was handled, we include the following response headers whenever an Idempotency-Key is used:
HeaderDescription
Idempotency-KeyEchoes the key used in the request, confirming it was recognized and applied
Idempotency-StatusIndicates how the request was processed:
new – First execution of the key
replayed – Cached response from an earlier identical request
Example: 
HTTP/1.1 200 OK
Idempotency-Key: 6aa2f8a3-4ef4-4899-8234-d45a93d1f191
Idempotency-Status: replayed
These headers are useful for debugging retries and understanding whether a result was replayed or newly generated.

​
Best Practices

  • Use a UUIDv4 or another random, high-entropy string to generate keys.
  • Only reuse a key if retrying the same exact request.
  • Never use the same key for different operations, endpoints, or payloads.
PCCI will reject repeat requests with the same key if the parameters differ from the original, to prevent accidental misuse.

​
When to Use Idempotency

Idempotency is recommended for any request where duplication would have negative effects, including:
  • Creating payments, invoices, or subscriptions
  • Modifying product or user data
  • Sending webhooks or external callbacks
  • Initiating long-running or asynchronous tasks

​
Summary

HeaderRequiredDescription
Idempotency-KeyOptional (but recommended for all POST/PUT/PATCH requests)Ensures that a given operation is only performed once, even if retried
PCCI’s idempotency layer does not cache invalid requests — if a request fails validation or is rejected before execution, the key will not be stored. You are free to retry those requests. Need implementation help or debugging assistance? Reach out to [email protected] and include your request payload and idempotency key.