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:
- First request: The API processes the request normally and caches the response
- Subsequent requests with the same key: The API returns the cached response without re-executing the operation
- 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.
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.
