Errors
Errors
Every response, success or failure, uses one envelope. Use the HTTP status to decide what to do and message to explain it.
Response envelope
statusCode
The HTTP status as a number, for example 400.
message
Human-readable explanation. This is the text to show or log.
timestamp
When the response was produced (date-time).
data
A string on errors. On success it holds the resource.
successful
false on errors, true on success.
Errors have no separate code string; read statusCode and message. The web app shows message to users when a request fails.
HTTP status reference
400 Bad Request
The body, a parameter or a field value is invalid. Read message, fix the request, then resend.
401 Unauthorized
No bearer token, or it is expired or invalid. Authenticate again and resend.
403 Forbidden
The caller is not allowed to act on this organization, or the X-Client-Id header is missing. Check the header and your access.
404 Not Found
The organization reference or invoice ID does not exist. Check the IDs and the path.
409 Conflict
The request conflicts with the current state of the resource. Fetch the resource and decide before retrying.
500 Internal Server Error
Unexpected failure on the server. Retry later; contact support if it persists.
These are the only error statuses the API documents. Successful creates return 200.
Validation failures
A request the API cannot accept returns 400 in the same envelope, with the explanation in message. The example on the right posts to the POS invoice create endpoint (POST /api/v1/organizations/{organizationReference}/invoices/pos) with customerType set to a value outside its allowed list (BUSINESS, INDIVIDUAL, GOVERNMENT). The exact message text depends on the failure, so treat the one shown as a placeholder.
Retry guidance
Retry
500 and network timeouts, with a short delay that grows between attempts.
Retry after re-authenticating
401, once, with a fresh access token.
Do not retry unchanged
400, 403, 404, 409. Change the request, access or state first.
Avoid retry storms
Cap the number of attempts and stop when the operation is no longer useful. Without idempotency keys, a retried create can produce a duplicate, so check whether the first attempt succeeded before resending.
Troubleshooting actions
Coming soon Soon
The following are planned and are not part of the API today. Do not build against them.
Rate limits and 429
A request limit with a Retry-After header.
422 and 503
A separate validation status and a service-unavailable status.
Idempotency keys
An Idempotency-Key header so retried writes are safe.
X-Request-Id
A correlation ID to quote when contacting support.
Machine-readable error codes
Stable code strings alongside message.