MG Crypto
Dashboard

Idempotency

Safely retry write requests without accidentally creating the same invoice or payment link twice. Send an Idempotency-Key and a retry returns the original result instead of making a new one.

How it works

Add an Idempotency-Key header to any POST request. The value should be a unique string you generate per logical operation — a UUID is ideal. If a request with the same key arrives again, the API returns the result of the first request instead of performing the action a second time.

curl -X POST "https://markgroup.app/api/v1/invoices" \
  -H "Authorization: Bearer $MG_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 8f14e45f-ceea-467a-9575-3c1e2b7f0a91" \
  -d '{ "amount_usd": 100 }'

Replays

When a request is served from a stored result, the response includes an Idempotent-Replay: true header so you can tell it apart from the original. Keys are retained for 24 hours.

Conflicts

Two situations return 409 conflict:

  • You reuse a key that is still being processed (a request with that key is in flight).
  • You reuse a key with a different request body — the key is tied to the exact payload it first saw.

Generate one key per operation

Create a fresh key each time you intend to make a new invoice or link, and reuse that same key only for retries of that specific operation. Don't share one key across different requests.

Combine idempotency with retry-on-5xx from the Errors guide for a robust integration that never double-charges on a flaky connection.