Skip to main content

​
Response envelope

Every action-style response follows a consistent shape. On success: 
{ "success": true, "data": { /* … */ } }
On failure: 
{
  "success": false,
  "error": "Variant is required",        // human-readable, for your logs
  "errorCode": "VARIANT_REQUIRED",        // stable, branch on this
  "fieldErrors": [                          // present for input validation
    { "field": "variantId", "code": "VARIANT_REQUIRED" }
  ]
}
Responses may also carry businessRuleWarnings (when a rule warned but allowed the action) and approvalRequested (when an approval policy intercepted a validation). Always branch on errorCode, not on the error text — the text is for logs and may change or be localized; the code is stable.

​
HTTP status mapping

Errors are categorized, and the category determines the HTTP status (with a few per-code overrides):
CategoryHTTPExamples
Validation400VALIDATION_ERROR, MISSING_REQUIRED_FIELD, VARIANT_REQUIRED
Auth401UNAUTHORIZED, FORBIDDEN
Not found404RECORD_NOT_FOUND, PLAN_NOT_FOUND
Business422BUSINESS_RULE_VIOLATION, INSUFFICIENT_STOCK
Rate limit429RATE_LIMIT_EXCEEDED
External502EXTERNAL_SERVICE_ERROR, EXTERNAL_SERVICE_TIMEOUT
Database / Config / Unknown500DATABASE_ERROR, UNKNOWN_ERROR
A notable override: PLAN_ALREADY_VALIDATED returns 409 Conflict rather than 422.

​
Common error codes

CodeMeaningWhat to do
UNAUTHORIZEDToken missing, invalid, revoked, or expiredRe-authenticate / issue a new token
FORBIDDENToken lacks the required permissionGrant the permission on the token; don’t retry as-is
VALIDATION_ERRORInput failed validationInspect fieldErrors; fix the payload
RECORD_NOT_FOUND / PLAN_NOT_FOUNDResource doesn’t exist (or not in your org)Verify the id; don’t retry
BUSINESS_RULE_VIOLATIONA business rule blocked the actionRead the message / warnings; adjust the request
PLAN_ALREADY_VALIDATEDPlan is past the state you’re acting onRe-fetch the plan’s current status
RATE_LIMIT_EXCEEDEDToo many requests (if enforced upstream)Back off and retry
DATABASE_ERROR / UNKNOWN_ERRORUnexpected server errorRetry once; escalate if persistent
There are over a hundred specific codes (validation, plan/item operations, file upload, API tokens, …). Each endpoint documents the ones it can return in the API Reference tab.

​
Localized messages

Error codes are decoupled from display text so messages can be shown in the user’s language. In the web app, codes are translated to English or French; integrators should rely on the code and render their own message if needed.