idempotency_key_reuse

HTTP 409

When you see this

POST /api/v1/intents allows one active intent per (merchant account, payout namespace, chain, wallet, token). If you send the same terms for a wallet that already has an active intent, that is not an error. You get the existing intent back with created: false and a fresh widgetToken.

You get this error when the destination matches but the terms differ. For example, a different priceUnits or a different oneTime. A different chain or token counts as a different destination.

Nothing changes when this error returns. The existing intent keeps its terms and its deposit address. No second intent is created. Creates with no destination fields never see this error. They always create a new intent.

What the response looks like

{
  "error": {
    "code": "idempotency_key_reuse",
    "message": "This payout wallet already has an active intent with different terms.",
    "request_id": "req_1a2b3c4d5e6f7a8b9c0d1e2f",
    "docs": "https://canopypay.io/errors/idempotency_key_reuse"
  }
}

What to do

To retry the same operation, resend the same body. It returns the existing intent and rotates its widget token. Save the intent ID and reuse it for an existing checkout.

To use different terms for the same wallet, do one of these:

• Complete the one-time intent. A one-time intent frees its wallet once the price is reached.
• Archive the active intent to free the wallet.
• Use a different payout wallet.