Troubleshooting
Identify the failing step, preserve unknown outcomes, and recover without duplicate payments.
On this page
Start with context and evidence
- Confirm merchant, integration, environment, and the key deployed to the backend.
- Capture
x-carden-request-id, the response status, and safe validation issue paths. - Check whether the failure concerns invoice data, preparation, Stripe execution, or report delivery.
- Inspect the source of truth for the relevant stage before taking corrective action.
Common issues
| Symptom | Likely checks | Recovery |
|---|---|---|
| Cannot see a merchant | AuthKit identity, accepted membership, current organization, and role. | Ask an owner to correct membership; do not share an account. |
| QuickBooks connected, invoices missing | Selected company, lookback window, queued or failed import, source record status. | Inspect sync status and source invoice; request an appropriate resync. |
| 401 response | Missing, malformed, revoked, or wrong Carden key. | Correct the Bearer credential and retest; never use a Stripe key. |
| 403 response | Insufficient scope, restricted settings, or wrong organization/environment context. | Use minimum required access in the correct context. |
| 400 enrichment response | JSON shape, required nullable fields, field spelling, and integer amounts. | Validate against CanonicalInvoice; send JSON with Content-Type application/json. |
| 422 enrichment response | Arithmetic, missing product code or unit, unsupported quantities, tax or discount representation. | Fix factual input or route to an exception; do not fabricate missing facts. |
| Captured report missing | Outbox state, delivery response, duplicate acknowledgment, and dashboard environment. | Retry the same report event independently of the payment. |
| Unexpected refund volume | Cumulative versus incremental amounts and duplicate or out-of-order observations. | Reconcile by attempt and current provider state; do not sum snapshots. |
Resolve invoice validation failures
Check the issue's field path first. All amount fields are integer minor units. The canonical quantity is a string, while the current Stripe transformer requires a positive integer quantity. The invoice can represent missing codes as null, but enrichment may require them. This is a real data exception, not a reason to substitute a made-up code.
Choose transaction-level or line-item tax and discounts deliberately. Line-item totals must reconcile to invoice totals when using line-item representation. Keep shipping separate and ensure subtotal plus tax plus shipping minus discounts equals total.
Recover a report backlog
- Keep payment execution and report delivery separated. Identify the oldest unacknowledged outbox events.
- Correct authentication or validation problems before replaying permanent failures.
- For a transient failure, retry the same payload and event ID with bounded backoff and jitter.
- Treat
duplicate: trueas an acknowledgment. Mark that report delivered rather than producing a new ID. - Reconcile unresolved or ambiguous attempts with Stripe in your backend, then emit new observations where needed.
If a payload itself was wrong, retain the rejected event for audit and produce a corrected event with a new identity under an explicit correction policy. Reusing an accepted event ID is not an update operation.
When to escalate
Escalate repeated server failures, unauthorized activity, incorrect organization routing, or a backlog your worker cannot clear. Provide safe identifiers and response details. State explicitly whether payments are processing normally, reports are delayed, or actual Stripe outcomes are unknown.