API: Idempotency key conflict

Quick fix

Read the commands before running them. Anything that restarts a service, deletes data or changes permissions should be tried on a non-production system first.

# Generate unique idempotency key per request
import uuid
idempotency_key = str(uuid.uuid4())
headers = {'Idempotency-Key': idempotency_key}
# Store key with request params
# Retry with same key if network fails

How to diagnose API errors

API integration errors are usually a contract mismatch: the client and the server disagree about authentication, encoding, size limits, or which version of the API is in play. Because most API clients swallow the response body and surface only the status code, the single highest-value debugging habit here is to log the full response, headers included, before you touch any code.

If the quick fix above does not resolve it, work through these steps. They apply to this whole class of error, not just to this one message, which is usually what saves the time.

1. Reproduce the failing call with curl -v outside your application. If curl succeeds and your client fails, the bug is in your client's header or serialisation layer, not on the server.
2. Print the exact Authorization header being sent (redact the secret, keep the prefix). A missing Bearer  prefix and a trailing newline from an environment file are the two most common causes of a mystery 401.
3. Check for an intermediate proxy. A 413 or 502 from nginx, Cloudflare or an API gateway looks identical to one from your application, but is fixed in completely different config.
4. For webhooks, verify the signature against the raw request body. Any middleware that parses and re-serialises JSON before your handler runs will silently break HMAC verification.
5. Confirm the API version. Deprecation errors and unexpected schema changes almost always trace back to a pinned version header that was never updated, or one that was never pinned at all.

Tools worth reaching for

• curl -v
• httpie
• Postman/Bruno
• mitmproxy
• ngrok (for webhooks)

Authoritative references

Primary documentation for this error, worth reading before applying any fix in production.

📖 stripe.com

Related API errors

• API Gateway 413: Payload too largeRequest body exceeds API Gateway/Lambda payload limits (10MB REST, 6MB HTTP API by default).
• API: Bearer token missing or malformedAPI requires Bearer token in Authorisation header but token is missing or invalid format.
• API: CORS preflight request failedBrowser sent OPTIONS preflight but server returned error. Need to handle OPTIONS requests.
• API: Endpoint deprecatedAPI endpoint is deprecated and will be removed. Need to migrate to new version.
• API: HTTP method override not workingSome proxies/firewalls block PUT/PATCH/DELETE. Need to use X-HTTP-Method-Override header.
• API: JSON schema validation failedRequest body doesn't match expected JSON schema. Missing required fields or wrong types.
• API: Rate limit exceeded (per minute)Too many API requests in the last minute. Need to implement rate limiting or backoff.
• API: Request payload too largeAPI request body exceeds maximum allowed size. Need to reduce payload or use chunking.

See all 14 API errors →

Browse other categories

• HTTP 494xx client errors, 5xx server errors, redirects, headers and protocol problems.
• JavaScript 42npm resolution, async pitfalls, hydration, memory limits and runtime type…
• Database 41Connections, deadlocks, constraints, replication and memory limits.
• AI 35Rate limits, context windows, GPU memory and model-serving failures.
• Network 35Refused connections, timeouts, resets, MTU problems and port exhaustion.
• Python 35Imports, virtual environments, encoding, concurrency and dependency conflicts.
• Kubernetes 34CrashLoopBackOff, ImagePullBackOff, OOMKilled, RBAC, scheduling and storage.
• Docker 27Daemon connectivity, disk space, image pulls, ports and architecture mismatches.
• System 26Disk space, systemd units, file descriptors, OOM killer and scheduled jobs.
• Cloud 25IAM permissions, quotas, service limits and credential failures.
• Security 25JWT validation, CSRF, OAuth grants, SELinux, SSH host keys and CSP.
• TLS 24Untrusted authorities, expiry, hostname mismatch, chains and cipher negotiation.

Something missing or wrong?

This entry is maintained by hand. If the fix is out of date, incomplete, or you have a better one, email a correction and it will be reviewed.