`idempotency_key_reused`

The `Idempotency-Key` was already used for a different request. Use a new key per distinct request.

HTTP 422The request was understood but refused as sent. Change it before retrying.

When it fires

This Idempotency-Key was already used, within the last 24 hours, for a request with a different body. Repull refuses rather than guess which one you meant, and nothing was done. It almost always means one key was generated once and reused across a loop, or a corrected request was sent with the key of the one it corrects.

Response shape

Every Repull error follows the same envelope. The code is stable and safe to switch on.

{
  "error": {
    "code": "idempotency_key_reused",
    "message": "This `Idempotency-Key` was already used for a request with a different payload.",
    "fix": "Generate a NEW key per distinct request — a fresh UUID at the point you build the request, not one reused across a loop. Reuse the same key ONLY when retrying that exact request.",
    "field": "Idempotency-Key",
    "value_received": "msg-164743",
    "docs_url": "https://repull.dev/docs/errors/idempotency_key_reused",
    "request_id": "req_01J5X7Y8Z9ABCDEF12345678"
  }
}

How to fix

Generate a new key for each distinct request, at the point where you build it: a UUID, or an id derived from what the request is for (for example `offer-<inquiryId>-<attempt>`).
Reuse a key only when retrying that exact request, with the same body.
After correcting a request that was refused, send the corrected one with a new key.

Common gotchas

Keys are scoped to your workspace and last 24 hours. A key derived only from a conversation id collides with the next message you send in that conversation.
The comparison is on the method, the path and the exact bytes of the body. Re-serializing the same data in a different field order counts as a different body, so when you retry, resend the body you built the first time rather than rebuilding it.

Examples

curl

# One key per distinct message
curl -X POST https://api.repull.dev/v1/conversations/164743/messages \
  -H "Authorization: Bearer sk_live_YOUR_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"message": "Your check-in details are ready."}'

TypeScript

import { randomUUID } from 'node:crypto'

for (const conv of conversations) {
  const key = randomUUID() // new for every distinct request, reused only on retry of this one
  await sendWithRetry(conv.id, { message: welcomeText(conv) }, key)
}

If you're an AI agent

The Idempotency-Key was already used for a different request body. Nothing was done. Generate a new key per distinct request; reuse a key only to retry that exact request.

Error reference — the full table of error codes
Using Repull from AI agents — patterns for handling errors in agent loops
Idempotency Keys
idempotency_key_in_use

Hit an error that isn't covered? Email hello@repull.dev with the request id from the response headers.

Previous← idempotency_key_in_use

idempotency_key_reused