Skip to main content

idempotency-key-reuse

Type URI: https://developer.risepeople.com/errors/idempotency-key-reuse HTTP status: 409 Conflict Format: application/problem+json (RFC 7807)

When this fires​

Idempotency-Key headers cache the response of a mutating request for 24 hours so you can safely retry on network errors. Within that window:

  • Same key + same body → the original response is replayed, side effects happen exactly once.
  • Same key + a different body → this 409, because the platform can't tell which request you really wanted.

This is almost always a client bug — either an Idempotency-Key that wasn't fresh, or a payload that changed between retries.

Example response​

{
  "type":   "https://developer.risepeople.com/errors/idempotency-key-reuse",
  "title":  "Idempotency Key Conflict",
  "status": 409,
  "detail": "The Idempotency-Key has already been used with a different request payload.",
  "instance": "/v1/payroll/runs"
}

How to fix it​

  1. Generate a fresh key per logical request. A common pattern is one UUID per "operation the user clicked once" — not one UUID per process or per session.
  2. Don't mutate the request body between retries. If you need to change the payload, use a new Idempotency-Key.
  3. If you genuinely want to overwrite a prior request, wait out the 24-hour window or send the new request with a new key.

Discard the old key after a 409 — re-using it again will keep returning 409.