The Fix
pip install stripe==14.4.0a2
Based on closed stripe/stripe-python issue #849 · PR/commit linked
Production note: This usually shows up under retries/timeouts. Treat it as a side-effect risk until you can verify behavior with a canary + real traffic.
@@ -115,10 +115,27 @@ def _static_request(
params=None,
):
+ params = None if params is None else params.copy()
+ api_key = util.read_special_variable(params, "api_key", api_key)
+ idempotency_key = util.read_special_variable(
repro.py
stripe.Customer.create(
name="John Doe",
email=email,
idempotency_key="test-key-12345",
)
verify
Re-run the minimal reproduction on your broken version, then apply the fix and re-run.
fix.md
Option A — Upgrade to fixed release\npip install stripe==14.4.0a2\nWhen NOT to use: Do not use this fix if you are relying on behavior from previous versions that may have changed.\n\n
Why This Fix Works in Production
- Trigger: v4.0.0 `idempotency_key` parameter unknown
- Mechanism: The API methods did not handle the `idempotency_key` parameter correctly, causing errors
- Why the fix works: Fixes the issue where using the `idempotency_key` parameter caused a 'Received unknown parameter' error in API requests. (first fixed release: 14.4.0a2).
Production impact:
- If left unfixed, the same config can fail only in production (env differences), causing startup failures or partial feature outages.
Why This Breaks in Prod
- Shows up under Python 3.7.3 in real deployments (not just unit tests).
- The API methods did not handle the `idempotency_key` parameter correctly, causing errors
- Production symptom (often without a traceback): v4.0.0 `idempotency_key` parameter unknown
Proof / Evidence
- GitHub issue: #849
- Fix PR: https://github.com/stripe/stripe-python/pull/850
- First fixed release: 14.4.0a2
- Reproduced locally: No (not executed)
- Last verified: 2026-02-08
- Confidence: 0.85
- Did this fix it?: Yes (upstream fix exists)
- Own content ratio: 0.70
Discussion
High-signal excerpts from the issue thread (symptoms, repros, edge-cases).
“We have just released version 4.0.1 of the package which has the fix for this issue. Rolling back to previous major is no longer necessary.”
“@newenegue thanks a lot for the report. There is definitely something wrong where some API methods don't handle options like idempotency_key and api_key properly but…”
“@remi-stripe thanks for the response! We've rolled back to v3.5.0 and everything is working as expected.”
Failure Signature (Search String)
- v4.0.0 `idempotency_key` parameter unknown
- Any of our requests to `POST /v1/subscriptions`, `POST /v1/invoices` and `POST /v1/customers/:id` are failing with `Received unknown parameter: idempotency_key`
Copy-friendly signature
signature.txt
Failure Signature
-----------------
v4.0.0 `idempotency_key` parameter unknown
Any of our requests to `POST /v1/subscriptions`, `POST /v1/invoices` and `POST /v1/customers/:id` are failing with `Received unknown parameter: idempotency_key`
Error Message
Signature-only (no traceback captured)
error.txt
Error Message
-------------
v4.0.0 `idempotency_key` parameter unknown
Any of our requests to `POST /v1/subscriptions`, `POST /v1/invoices` and `POST /v1/customers/:id` are failing with `Received unknown parameter: idempotency_key`
Minimal Reproduction
repro.py
stripe.Customer.create(
name="John Doe",
email=email,
idempotency_key="test-key-12345",
)
Environment
- Python: 3.7.3
What Broke
Requests to create customers and subscriptions failed with unknown parameter errors.
Why It Broke
The API methods did not handle the `idempotency_key` parameter correctly, causing errors
Fix Options (Details)
Option A — Upgrade to fixed release Safe default (recommended)
pip install stripe==14.4.0a2
When NOT to use: Do not use this fix if you are relying on behavior from previous versions that may have changed.
Use when you can deploy the upstream fix. It is usually lower-risk than long-lived workarounds.
Option D — Guard side-effects with OnceOnly Guardrail for side-effects
Mitigate duplicate external side-effects under retries/timeouts/agent loops by gating the operation before calling external systems.
- Place OnceOnly between your code/agent and real side-effects (Stripe, emails, CRM, APIs).
- Use a stable key per side-effect (e.g., customer_id + action + idempotency_key).
- Fail-safe: configure fail-open vs fail-closed based on blast radius and spend risk.
Show example snippet (optional)
onceonly.py
from onceonly import OnceOnly
import os
once = OnceOnly(api_key=os.environ["ONCEONLY_API_KEY"], fail_open=True)
# Stable idempotency key per real side-effect.
# Use a request id / job id / webhook delivery id / Stripe event id, etc.
event_id = "evt_..." # replace
key = f"stripe:webhook:{event_id}"
res = once.check_lock(key=key, ttl=3600)
if res.duplicate:
return {"status": "already_processed"}
# Safe to execute the side-effect exactly once.
handle_event(event_id)
When NOT to use: Do not use this to hide logic bugs or data corruption. Use it to block duplicate external side-effects and enforce tool permissions/spend caps.
Fix reference: https://github.com/stripe/stripe-python/pull/850
First fixed release: 14.4.0a2
Last verified: 2026-02-08. Validate in your environment.
When NOT to Use This Fix
- Do not use this fix if you are relying on behavior from previous versions that may have changed.
- Do not use this to hide logic bugs or data corruption. Use it to block duplicate external side-effects and enforce tool permissions/spend caps.
Verify Fix
verify
Re-run the minimal reproduction on your broken version, then apply the fix and re-run.
Did This Fix Work in Your Case?
Quick signal helps us prioritize which fixes to verify and improve.
Prevention
- Capture the exact failing error string in logs and tests so you can reproduce via a minimal script.
- Pin production dependencies and upgrade only with a reproducible test that hits the failing path.
Version Compatibility Table
| Version | Status |
|---|---|
| 14.4.0a2 | Fixed |
Related Issues
No related fixes found.
Sources
We don’t republish the full GitHub discussion text. Use the links above for context.