Errors & versioning
Predictable JSON envelopes for failures and paginated lists.
Last updated 2026-09-01
Error shape
Failed requests return JSON with at least success: false and a human-readable message. Validation failures may also include field-level details (for example fieldErrors).
Example
{
"success": false,
"message": "Customer name is required"
}List shape
Paginated collections commonly look like:
| Field | Meaning |
|---|---|
| success | true on success |
| total | Total matching rows |
| limit | Page size |
| offset | Skip count |
| data | Array of records |
Always drive sync jobs from total, limit, and offset rather than assuming a fixed page size.
Versioning
The public tenant API is served under /api without a separate /v1 prefix in the current product. Breaking changes are communicated via docs changelog and release notes when published. Prefer additive clients: ignore unknown fields.
Constraints
- HTTP status codes accompany the JSON body — check both
- Unauthorized session or credentials return unauthorized messages
- Rate limiting may reject bursts; back off and retry