Idempotency and retries

With an Idempotency-Key on each request that changes something, you can retry safely and nothing is done twice.

The rule

Every POST that moves money, calls a supplier or makes something needs an Idempotency-Key header. The contract marks each one. Without it, the answer is 400 IDEMPOTENCY_KEY_REQUIRED.

• The key is a string of 16 to 128 characters.
• Make a new key for each new action, such as a random UUID.
• Use the same key, with the same body, when you retry that action.

curl -X POST https://YOUR_API_ADDRESS/v1/channel/dns/records \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Idempotency-Key: 7f3a2c9e-4b1d-4e8a-9c2f-0d6b5a1e3f70" \
  -H "Content-Type: application/json" \
  -d @change.json

What a repeat gets

You send	You get
The same key and body, after the first answer	The first answer again, exactly. Nothing is done twice.
The same key and body, while the first is still running	409 PAYMENT_IN_FLIGHT. Wait a moment, then retry.
The same key with a different body	400 IDEMPOTENCY_KEY_REUSED. Nothing changes. Use a new key.

The channel API answers a reused key with a different body with 409 IDEMPOTENCY_KEY_REUSED.

A key is tied to the person or key that sent it. Another caller who reuses your key gets IDEMPOTENCY_KEY_REUSED, never your answer.

A request that fails gives its key back. Your retry with the same key then runs as a fresh attempt.

Keys are kept for 24 hours. After that, the same key counts as new.

Secrets are shown once

Creating an API key or a webhook endpoint returns the secret once. A replay of the same key returns the same record with the secret as null, because only a hash is kept. If you lost it, revoke the key or rotate the secret.

Retrying well

• Retry on a timeout, a lost connection or a 5xx answer, with the same key.
• Do not retry a 4xx answer unchanged. Read the message, fix the request, and use a new key.
• On 429, wait for the seconds in Retry-After.
• Work that takes time, such as registering a domain, answers 202 at once. Read the result later, or wait for its webhook.

If something goes wrong

Contact Taji support at [email protected] or +250782009639.