Errors
Interpret HTTP errors and field validation issues, then retry the right operation safely.
On this page
Structured Stripe API errors
The enrichment API uses an error object with type, a human-readable message, and optional issues. Each issue contains a machine-readable code, field path, and message. Always read the HTTP status as well; a successful transport does not imply a successful operation.
{
"error": {
"type": "validation_error",
"message": "The canonical invoice cannot produce a valid Stripe enrichment.",
"issues": [
{
"code": "required",
"path": "invoice.lineItems[0].productCode",
"message": "Must be a non-empty string."
}
]
}
}Keep x-carden-request-id from the response header in your diagnostic record. QuickBooks operations can return a string error instead; handle the endpoint's documented shape rather than assuming one global error envelope.
Status and recovery
| Status / failure | Interpretation | Recovery |
|---|---|---|
| 400 | Invalid JSON, field shape, or request values. | Correct the body. Do not retry unchanged indefinitely. |
| 401 | Missing or invalid Carden authentication. | Check Bearer formatting and key status; use a Carden key, never a Stripe key. |
| 403 | Insufficient permission or wrong authorized context. | Check scopes, settings, merchant, and environment. |
| 404 | Requested resource or sync state not found in scope. | Verify the identifier and context before creating replacement work. |
| 409 | Conflicting event identity or reported state, when returned. | Compare the original event and payload; a reused event ID is not an update. |
| 413 | Request payload is too large. | Send only the documented allowlisted fields; never include raw provider objects. |
| 422 | Input has the right shape but fails domain validation. | Inspect issue paths and correct factual data or route to an exception. |
| 429, if returned | Requests are being limited. | Honor Retry-After when present and use bounded backoff. |
| 5xx | Server, configuration, or downstream failure. | Retry safe preparation or report delivery with backoff; escalate persistent errors. |
| Timeout / connection error | No definitive acknowledgment reached your backend. | Retry the same report event; reconcile unknown Stripe payment outcomes separately. |
Enrichment validation issue codes
| Code | What to inspect |
|---|---|
required / invalid_format | Missing source facts, empty required strings, currency, or quantity formatting. |
invalid_integer / out_of_range | Safe integer minor units, nonnegative values, and supported item counts. |
too_long / duplicate | Adapter field limits or repeated line sequence identifiers. |
arithmetic_mismatch / arithmetic_overflow | Line and invoice totals or values outside safe integer arithmetic. |
tax_mutual_exclusion / tax_representation_incomplete | Conflicting or incomplete tax representation. |
discount_mutual_exclusion | Discount represented at incompatible levels. |
A validation issue is an instruction to inspect the source and mapping, not permission to synthesize data. Preserve null or missing source facts and have an authorized reviewer resolve the exception.
Keep payment retries separate
If Stripe itself times out, keep the attempt unknown until your backend retrieves the provider state or receives a verified event. Do not change unknown to failed merely because the caller lost its connection.