Stripe troubleshooting
Recover Stripe preparation, execution, correlation, and report delivery failures without duplicating a payment.
On this page
Identify the failed Stripe stage
- Confirm the merchant, Carden environment, Stripe integration, key, and Stripe mode.
- Save x-carden-request-id, preparation.id, attemptId, eventId, and known Stripe object IDs.
- Identify whether the failure occurred during source lookup, Carden preparation, merchant Stripe execution, provider webhook handling, Carden report delivery, or settlement reconciliation.
- Inspect the authoritative system for that stage and correct only the failed operation.
Resolve preparation failures
| Failure | Recovery |
|---|---|
| 400 | Correct JSON shape, required fields, integer amounts, or strict unsupported properties. |
| 401 / 403 | Use an active Stripe-integration Carden key in the correct context with required scopes. |
| 409 source or revision | Finish refresh work and review the current source, link, revision, and idempotency input. |
| 422 domain validation | Correct factual source or mapping data; keep unsupported records in exception review. |
| Timeout / 5xx | Retry the same safe preparation under a bounded policy; preparation does not execute Stripe. |
Inline JSON bodies are currently limited to 1,000,000 bytes and stored-invoice preparation bodies to 16,384 bytes. Send unencoded UTF-8 application/json and only documented fields.
Reconcile Stripe execution separately
- Use the merchant's Stripe idempotency key and persisted attempt record to retrieve current provider state.
- Keep processing or ambiguous transport results unknown until provider evidence establishes a definitive state.
- Verify Stripe webhook signatures over the raw provider request in the merchant backend.
- Normalize cumulative captured and refunded totals rather than summing duplicate events.
- Never treat successful Carden preparation as a successful Stripe payment.
Recover report delivery
| Result | Action |
|---|---|
| 2xx, including duplicate: true | Mark the immutable outbox event delivered. |
| 408, 429, 5xx, timeout, connection failure | Retry the same eventId and body with bounded backoff. |
| 401 / 403 | Pause delivery and repair or rotate the Carden key. |
| 400 / 422 | Quarantine for factual correction; a corrected observation has a new eventId. |
| 409 | Reconcile event identity, provider aliases, amount, currency, cumulative totals, and occurrence order. |
Payment-report bodies are currently limited to 32,768 bytes. Raw Stripe objects do not belong in reports. Preserve the original payment result even when Carden delivery fails.
Escalate with safe evidence
Provide the merchant, environment, failed stage, time range with timezone, safe request and resource IDs, HTTP status, and payment impact. Redact Carden keys, Stripe secrets, client secrets, webhook secrets, and customer card data.
A prepared response or captured report is not settlement evidence. If qualification or cost is unclear, leave verified savings unestablished until actual settlement economics and an evidenced baseline are available.