Skip to main content

​
Overview

Network failures, timeouts, and other transient issues can cause your application to retry requests without knowing whether the original request succeeded. This can lead to duplicate resources being created in the target system. The Maesn API supports idempotency for POST requests, allowing you to safely retry operations without creating duplicates. By including an idempotency-key header, the API guarantees that multiple identical requests will have the same effect as a single request.

​
How it works

When you send a POST request with an idempotency-key header:
  1. First request: The API processes the request normally and caches the response
  2. Subsequent requests with the same key: The API returns the cached response without re-executing the operation
  3. Same key with different body: The API returns an error (the key cannot be reused for different data)
Idempotency keys are scoped to your tenant and user, so different users can safely use the same key values.

​
Supported endpoints

​
Using the idempotency key

Include the idempotency-key header in your POST request:

​
Response behavior

​
Error codes

​
409 Conflict - Request still processing

If you retry a request while the original is still being processed, the API returns a 409 error to prevent race conditions. What to do: Wait and retry after a short delay. The original request should complete shortly.

​
422 Unprocessable Entity - Key reused with different body

If you send a request with an idempotency key that was already used for a different request body, the API returns a 422 error. What to do: Use a new, unique idempotency key for the new request.

​
503 Service Unavailable - Cache unavailable

If the idempotency cache is temporarily unavailable, the API returns a 503 error to prevent potential duplicate operations. What to do: Retry after a short delay. Your request was not processed, so it is safe to retry with the same idempotency key.

​
Best practices

​
Generating keys

Use a value that uniquely identifies the logical operation you’re performing. Good approaches include:
  • UUIDs: 550e8400-e29b-41d4-a716-446655440000
  • Business identifiers: order-12345-invoice-001
  • Composite keys: {user-id}-{document-id}
The key can be any string value. We recommend using descriptive identifiers when possible, as they make debugging easier.

​
When to use idempotency keys

  • Always for production POST requests where duplicates would cause problems, for example capturing external invoices or creating journal entries
  • Especially when implementing retry logic for failed requests
  • When network conditions are unreliable

​
Key expiration

Idempotency keys are valid for 24 hours after the first request completes. After this period, the same key can be reused for a new request.
Do not rely on key expiration as part of your normal workflow. Always generate unique keys for distinct operations.
Last modified on October 7, 2026