Posta supports idempotency for safely repeating requests without risking duplicate operations. This is particularly useful when dealing with network issues or timeouts.

​
How idempotency works

The following diagram illustrates how idempotency works in the Posta API: To make an idempotent request, include an Idempotency-Key header with a unique value for that specific request. Posta’s system saves the result of the first request made with a given idempotency key. Subsequent requests with the same key return the identical result, including error responses.

​
Implementing idempotency

To implement idempotency in your API requests:
  1. Generate a unique idempotency key for each request (e.g., V4 UUID).
  2. Include the Idempotency-Key header in your POST, PUT, or DELETE requests.
  3. Use idempotency for all non-idempotent operations (POST, PUT, DELETE).
  4. Store keys temporarily to facilitate repeats for failed requests.
  5. For failed requests due to network errors or timeouts, repeat with the same idempotency key.
  6. Implement exponential backoff for retries to prevent overwhelming the API.

​
Example request with idempotency

curl -X POST https://api.posta.co/letters \
  -H "X-Api-Key: yourApiKeyHere" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 123e4567-e89b-12d3-a456-426614174000" \
  -d {yourPayloadHere}
Idempotency keys can be up to 255 characters long and are automatically removed after 24 hours.

​
Best practices

  • Generate a new key for each unique request to ensure proper idempotency.
  • Avoid reusing keys across different operations to prevent unexpected behavior.
  • Implement proper error handling and retry logic in your client applications.
  • Consider using a UUID generator to create unique idempotency keys.
Never reuse idempotency keys across different logical operations. This can lead to unexpected behavior.

​
Benefits of idempotency

Idempotency provides several advantages across different types of requests:
  1. Consistent responses: Ensures you receive the same response for repeated requests, regardless of the operation type.
  2. Preventing unintended duplicates: Protects against accidental duplication of operations due to network issues or user actions.
  3. Handling race conditions: Helps manage scenarios where multiple requests for the same operation are sent concurrently.
  4. Audit trail: Facilitates maintaining a clear record of operation attempts and their outcomes.
When repeating a request with the same idempotency key, the operation is not actually performed again. Instead, the stored result from the original request is returned. This ensures that the operation has the same effect, even if repeated multiple times.

​
Limitations

  • Idempotency is guaranteed only for 24 hours after the initial request.
  • GET requests are naturally idempotent and don’t require an idempotency key.

​
Error handling

For 4xx errors, check the error message before deciding whether to repeat the request. Some errors, such as validation errors, will persist even with repeated attempts.
Never reuse idempotency keys across different logical operations. This can lead to unexpected behavior.
Idempotency keys are tied to your API key. Using the same idempotency key with different API keys will not return the same result.