Skip to main content
We support idempotent requests so that you can retry safely without duplicates. This is important for actions that create resources, upload files, or modify data. For these actions, repeated requests can cause unwanted side effects.

​
The definition of idempotency

With idempotency, the same request, sent many times, has the same effect as one request. If your client gets a timeout or a network error, retry the request with the same idempotency key. We process the request only once.

​
The operation of idempotency

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 for that key. Each subsequent request with the same key:
  • Returns the original result, for success or for failure
  • Prevents duplicate processing of resource creation or updates
  • Keeps data integrity across retries
This behavior applies also if the first request caused a 500 or other server error. This keeps the result consistent for all outcomes.
The API ignores the Idempotency-Key in GET or DELETE requests.

​
Key Expiration

  • We store idempotency keys for 24 hours.
  • After expiration, the API treats the same key as a new request.
  • Keys can be up to 255 characters long.

​
Response Headers

When you use an Idempotency-Key, we include these response headers. They help clients see how we processed the request: Example:
These headers help you debug retries. They show if the API replayed the result or generated a new one.

​
Best Practices

  • Use a UUIDv4 or another random, high-entropy string to generate keys.
  • Use a key again only when you retry the same exact request.
  • Do not use the same key for different operations, endpoints, or payloads.
Prem API rejects a repeat request with the same key if the parameters differ from the original. This prevents accidental misuse.

​
When to Use Idempotency

Use idempotency for each request where duplication has negative effects. Use it when you:
  • Upload encrypted files
  • Create or modify resources with the API
  • Send webhooks or external callbacks
  • Start long-running or asynchronous tasks

​
Summary

The idempotency layer of Prem API does not cache invalid requests. If a request fails validation, or if we reject it before execution, we do not store the key. You can retry those requests. If you need help with implementation or with debugging, contact support@premai.io. Include your request payload and your idempotency key.