Errors
Interpret shared HTTP failures and validation issues, then retry only preparation or delivery operations that are safe.
On this page
Read status and endpoint envelope
Payment APIs use an error object with type, human-readable message, and optional issues. Each issue has code, field path, and message. QuickBooks management operations can return a top-level string error, so branch on HTTP status and the documented provider contract.
{
"error": {
"type": "validation_error",
"message": "The invoice cannot produce valid provider enrichment.",
"issues": [
{
"code": "required",
"path": "invoice.lineItems[0].productCode",
"message": "Must be a non-empty string."
}
]
}
}Retain x-carden-request-id in sanitized diagnostics. It identifies one HTTP request and is not a report event ID, payment identity, or idempotency key.
Status and recovery
| Status | Interpretation | Recovery |
|---|---|---|
| 400 | Invalid JSON, field shape, or values. | Correct the body; do not retry unchanged indefinitely. |
| 401 | Missing or invalid Carden authentication. | Repair Bearer formatting, expiry, or revocation. |
| 403 | Wrong provider, scope, context, permission, or integration state. | Use the authorized provider key and smallest required permission. |
| 404 | Resource not found in authorized scope. | Verify exact identifier and context before creating replacement work. |
| 408 | Server timed out reading a safe request. | Retry preparation or the same immutable report; never repeat a provider payment. |
| 409 | Source, revision, idempotency, event, alias, or cumulative-fact conflict. | Reconcile current source and payment facts. |
| 413 | Body exceeds the endpoint limit. | Send only documented allowlisted fields. |
| 415 | Unsupported content type or encoding. | Send unencoded UTF-8 application/json. |
| 422 | Structured input fails domain validation. | Correct factual source or mapping data. |
| 429 | Request rate exceeded. | Honor Retry-After when present and use bounded backoff. |
| 5xx / transport | Server or connection failure. | Retry safe preparation or immutable report delivery only. |
Maximum JSON bodies are 1,000,000 bytes for inline enrichment, 16,384 bytes for stored-invoice preparation, and 32,768 bytes for payment reports. The server counts streamed bytes rather than trusting Content-Length.
Interpret preparation issues
| Code | Inspect |
|---|---|
| required / invalid_format | Missing source facts, strict strings, currency, references, or quantities. |
| invalid_integer / out_of_range | Safe minor units, nonnegative values, quantities, and supported line counts. |
| too_long / duplicate | Provider limits or repeated sequence identities. |
| arithmetic_mismatch / arithmetic_overflow | Line, invoice, and provider totals. |
| tax_mutual_exclusion / tax_representation_incomplete | Conflicting or incomplete tax representation. |
| discount_mutual_exclusion | Discount represented at incompatible levels. |
An issue instructs you to inspect source and mapping. It never authorizes fabricated tax, product code, unit, quantity, reference, provider location, or catalog identity.
Keep payment retries separate
When provider execution itself is ambiguous, retrieve provider state and preserve unknown until evidence resolves it. A lost network response does not establish failed payment.