Skip to main content

Idempotency-Key

You can make requests idempotent by sending an Idempotency-Key header.

Behavior (defaults)​

  • The server stores the response for 24 hours
  • Repeating the same request with the same key returns the cached response
  • Reusing a key with a different payload returns 409 INVALID_ARGUMENT

Example​

curl -sS 'https://api.langbly.com/language/translate/v2' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -H 'Idempotency-Key: 4f96c8b5-0b2e-4ff7-9e20-3f8a2b3ac2f4' \
  -d '{"q":"Hello world","target":"nl"}'

Frequently asked questions​

Do I have to use a UUID as the Idempotency-Key value?​

No. The key can be any unique string you choose. A UUID is a common and safe choice to avoid collisions across requests, but it is not required.

What happens if I don't include the Idempotency-Key header?​

The request works normally, but without deduplication. The header is optional. If you do not need to safely retry requests, you can omit it.

I got a 409 INVALID_ARGUMENT error. What did I do wrong?​

You sent a second request with the same Idempotency-Key but a different request body (payload). The API rejects this to prevent accidental misuse. Use a new, unique key for a different request.

When can I reuse an Idempotency-Key?​

You can reuse the same key after 24 hours have passed since the first request. After that time, the cached response is no longer stored, and you can safely use the key again, even with a different payload, without getting a 409 error.