Idempotency
All create requests (POST) require an Idempotency-Key header. It makes retries safe: if a request times out or the connection drops, you can send it again with the same key without creating a duplicate.
curl https://api-test.worklogx.com/api/v1/customers \
-X POST \
-H "Authorization: Bearer wlx_test_YOUR_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 7c9e6679-7425-40de-944b-e07fc1f90ae7" \
-d '{"customerNumber": "K-10025", "name": "Muster Elektrotechnik GmbH"}'A successful create returns 201 Created with the new resource.
#Rules
| Situation | Result |
|---|---|
| Header missing or empty | 400 idempotency_key_required |
| Key longer than 128 characters | 400 validation_failed with errors: [{"field": "Idempotency-Key", "code": "too_long"}] |
| Same key, same request body | No new record. 201 with the resource created by the first request (in its current state). |
| Same key, different request body | 409 idempotency_key_reused |
Keys are scoped to the API client and the endpoint: the same key may be used once for POST /v1/customers and once for POST /v1/projects without conflict.
#Recommendations
- Generate a new random key, for example a UUID, for every logical create operation.
- Store the key together with the pending operation and reuse it for every retry of that operation.
- Never reuse a key for a different record.
#PATCH requests
PATCH endpoints do not use Idempotency-Key. Sending the same PATCH again sets the same values again.