Fundamentals
Error codes
Stable machine codes, their HTTP mapping, and which errors are worth retrying.
Every error carries a stable machine code: DOMAIN-AREA-NNNN.
{ "error": { "code": "CORE-AUTH-0001", "message": "…", "hint": "…", "trace_id": "…" } }Branch on code. message is translated to the reader's language and changes as the wording improves; code is a contract and does not.
Core codes
| Code | HTTP | Class | Meaning |
|---|---|---|---|
CORE-SYS-0001 | 500 | server | Unexpected internal error. Idempotent operations may be retried with backoff. |
CORE-SYS-0002 | 503 | server | A dependency (DB/Redis/queue) is temporarily unavailable. Retryable. |
CORE-SYS-0003 | 504 | server | Timed out. Retryable. |
CORE-SYS-0004 | 501 | server | Endpoint/feature not implemented. |
CORE-REQ-0001 | 400 | client | Malformed request (bad JSON, missing field). |
CORE-REQ-0002 | 422 | client | Validation failed; per-field errors in details[]. |
CORE-REQ-0003 | 404 | client | Resource does not exist (or is outside your workspace scope). |
CORE-REQ-0004 | 409 | client | State conflict (duplicate, precondition, in use). |
CORE-REQ-0005 | 409 | client | Idempotency key reused with a different body. |
CORE-REQ-0006 | 413 | client | Body exceeds the limit. |
CORE-AUTH-0001 | 401 | client | Missing or invalid credentials. |
CORE-AUTH-0002 | 403 | client | Authenticated but not permitted. |
CORE-RATE-0001 | 429 | client | Rate limited; honour Retry-After. |
CORE-TENANT-0001 | 404 | client | Workspace could not be resolved. |
CORE-TENANT-0002 | 403 | client | Workspace suspended. |
CORE-TENANT-0003 | 400 | client | A tenant-scoped route was reached without a tenant. |
Classes: client (4xx — fix the request; not retryable as-is) · server (5xx — transient; idempotent requests may be retried with backoff).
Module codes
Each module uses its own prefix: CRM-*, ERP-*, SHOP-*, B2B-*, ADS-*… The structure and classification are identical.
The module code you'll meet most often is the licence gate:
{ "error": { "code": "CRM-LIC-0001", "message": "This module is not in your subscription.",
"hint": "module_not_licensed" } }All eight modules return the same 403 with the same hint — so your integration can decide in a single branch.
Public API codes
/public/v1/... endpoints use a different envelope and vocabulary:
code | HTTP |
|---|---|
unauthorized | 401 |
forbidden | 403 |
not_found | 404 |
parameter_invalid | 400 |
conflict | 409 |
rate_limit_exceeded | 429 |
internal_error | 500 |
The retry rule
| Situation | Retry? |
|---|---|
429 | Yes — after waiting out Retry-After |
500 · 502 · 503 · 504 | Yes — exponential backoff + jitter |
408 (timeout) | Yes |
Other 4xx | No — the request is wrong; repeating it is still wrong |
Use Idempotency-Key on every write you might retry. Without it, a request in the "maybe it arrived" state creates a second record.