Error codes & responses

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):

Category	HTTP	Examples
Validation	`400`	`VALIDATION_ERROR`, `MISSING_REQUIRED_FIELD`, `VARIANT_REQUIRED`
Auth	`401`	`UNAUTHORIZED`, `FORBIDDEN`
Not found	`404`	`RECORD_NOT_FOUND`, `PLAN_NOT_FOUND`
Business	`422`	`BUSINESS_RULE_VIOLATION`, `INSUFFICIENT_STOCK`
Rate limit	`429`	`RATE_LIMIT_EXCEEDED`
External	`502`	`EXTERNAL_SERVICE_ERROR`, `EXTERNAL_SERVICE_TIMEOUT`
Database / Config / Unknown	`500`	`DATABASE_ERROR`, `UNKNOWN_ERROR`

A notable override: PLAN_ALREADY_VALIDATED returns 409 Conflict rather than 422.

Common error codes

Code	Meaning	What to do
`UNAUTHORIZED`	Token missing, invalid, revoked, or expired	Re-authenticate / issue a new token
`FORBIDDEN`	Token lacks the required permission	Grant the permission on the token; don’t retry as-is
`VALIDATION_ERROR`	Input failed validation	Inspect `fieldErrors`; fix the payload
`RECORD_NOT_FOUND` / `PLAN_NOT_FOUND`	Resource doesn’t exist (or not in your org)	Verify the id; don’t retry
`BUSINESS_RULE_VIOLATION`	A business rule blocked the action	Read the message / warnings; adjust the request
`PLAN_ALREADY_VALIDATED`	Plan is past the state you’re acting on	Re-fetch the plan’s current status
`RATE_LIMIT_EXCEEDED`	Too many requests (if enforced upstream)	Back off and retry
`DATABASE_ERROR` / `UNKNOWN_ERROR`	Unexpected server error	Retry 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.

API integration

API recipes

Platform & data model

Decision layer (reference)

Operations & infrastructure

Ingestion specs (reference)

Workflows (reference)

Tagging rules (reference)

Alerts (reference)

Error codes & responses

Response envelope

HTTP status mapping

Common error codes

Localized messages

​Response envelope

​HTTP status mapping

​Common error codes

​Localized messages

Response envelope

HTTP status mapping

Common error codes

Localized messages