Avoiding duplicate operations

Idempotency ensures an operation happens exactly once, no matter how many times the same request is retried. It prevents, for example, a duplicate quote when the connection drops mid-POST and you don’t know whether Cord received it.

The Idempotency-Key header

Every v1 API request that creates or changes something (POST, PATCH or DELETE) accepts the Idempotency-Key header. Generate a unique value per operation (for example, a UUID), store it with the operation and send it again on every retry with the same body:

curl -X POST "https://cordhq.app/api/v1/clientes" \
     -H "Authorization: Bearer $CORD_SECRET_KEY" \
     -H "Content-Type: application/json" \
     -H "Idempotency-Key: 5d9c2b7e-6f1a-4c3d-9e8b-2a1f0c7d6e5b" \
     -d '{ "empresa": "ACME Corp" }'

How Cord answers a repeat

• Same value, same body: Cord doesn’t run the operation again or count it against your quota. It returns the original response, with the same status code, and adds the Idempotent-Replayed: true header.
• Same value with a different body, method or route: 422 with the code idempotency_key_reused. Use a new value for each different operation.
• The first request is still running: 409 with idempotency_in_progress. Wait a few seconds and retry.
• 5xx and 429 errors: aren’t stored, so you can retry with the same value.
• Invalid value: 1 to 255 visible characters are accepted; otherwise, 400 with invalid_idempotency_key.
• No guarantee, no execution: if Cord can’t reserve the value, it returns 503 with idempotency_unavailable and doesn’t run the operation.

How long it lasts

Cord remembers each value for 24 hours, per API key: the same value sent with another key is a different operation. After 24 hours, the same value runs the operation again, so before retrying something older, check whether it already exists.

Without the header, every request runs as it arrives. A GET doesn’t need it: reading changes nothing.

SDK and MCP server

• The Node SDK (@flouviahq/node) sends an Idempotency-Key on every operation that writes and repeats the same value on its retries. You can pass your own with the idempotencyKey option.
• The MCP server tools that write accept an idempotency_key argument, with the same rule and the same duration.

Also

• Store the response id. When you create a quote (POST /api/v1/cotizaciones), the response includes data.id and data.folio. Store them in your system: if you already have an id for that operation, there’s no need to retry.
• Re-importing a catalog doesn’t duplicate it. CSV client import in the app updates the client that matches by tax ID or company name, and product import, the one that matches by SKU.

The API error codes and what they mean are in Error Handling.