Idempotency
How to retry a request safely, without creating a second case.
A request can time out, or fail with a network error or a 5xx, after we have already created the case.
Retrying it blindly could then create a second case. To retry safely, send an Idempotency-Key header with
the request and reuse the same key on every retry.
The header is supported on:
POST /v1/tax-registrationPOST /v1/trade-registration
Sending a key
Generate a unique key for each new request, for example a UUID, and send it as a header:
Idempotency-Key: 5b0c8e8a-7d2f-4d0e-9a51-1f0b6a4c2e11
The key is optional and can be up to 255 characters long. Requests without it work as before.
What a retry gets
| First request | A retry with the same key and the same body |
|---|---|
Finished with a 2xx or 4xx | Gets the first response again, with the same status code and body, and the header Idempotent-Replayed: true. Nothing is created. |
| Still running | 409 IDEMPOTENCY_REQUEST_IN_PROGRESS. Retry a few seconds later with the same key. |
Failed with a 5xx | Runs again. |
A key is tied to your account and to the endpoint: the same key on the tax and on the trade endpoint are two separate requests.
A key answers retries for 24 hours. A request that never finished, for example because our server restarted while handling it, frees its key after 10 minutes, and a retry then runs it again.
Errors
| Status | error_code | When |
|---|---|---|
400 | VALIDATION_ERROR | The Idempotency-Key header is empty, sent twice, or longer than 255 characters. |
409 | IDEMPOTENCY_REQUEST_IN_PROGRESS | The first request with this key has not finished yet. Retry with the same key. |
422 | IDEMPOTENCY_KEY_REUSED | The key was already used with a different request body. Use a new key for a new request. |
Need help?
If you have any questions or need assistance, feel free to contact us at info@beglaubigt.de.