Idempotency
Use idempotency keys to safely retry requests without creating duplicates.
Overview
The POST /invoices endpoint accepts an optional Idempotency-Key header. If you supply a key, Parseo stores the response for 24 hours. Any subsequent request with the same key (same API key + same key string) returns the cached response without re-processing the file.
Idempotency-Key: <your-unique-string>Use a UUID (v4) generated per upload attempt. Store it alongside the upload so you can retry safely if the network fails before you receive a response.
How it works
- Request arrives with
Idempotency-Key: k1. - If no cached response exists for
(teamId, apiKeyId, k1)→ process normally, cache the response. - If a cached response exists → return the cached
statusCode+responseBodyimmediately. No file is processed, no credits are consumed.
The cache key is (teamId, apiKeyId, idempotencyKey). Two different API keys using the same string do not collide — each key has its own namespace.
Concurrent requests
If two requests with the same Idempotency-Key arrive simultaneously, only one is processed. The second returns 409 Conflict with error code idempotency.request_in_progress. Retry after the first resolves.
Request body mismatch
If you reuse an idempotency key with a different file (detected by a hash of the request body), the API returns 409 Conflict with error code idempotency.key_reused_with_different_params. Each logical upload must use a unique key.
Key rotation and idempotency
Idempotency keys are scoped per API key. Each API key has its own independent idempotency namespace — two keys using the same idempotency key string do not collide.
When you rotate your API key, in-flight retries that switch to the new key lose their idempotency protection. A retry sent with the new key will be treated as a new request, potentially creating a duplicate invoice.
Mitigation: drain all in-flight retries before switching credentials. The old key remains valid for authentication during the grace period to allow you to do this safely.
Recommendations
- Generate a UUID per upload, not per retry. Store it so retries reuse the same key.
- If your system creates the invoice record before uploading, use the record's ID as the idempotency key.
- Do not share idempotency keys across different invoices.