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.

json
{ "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

CodeHTTPClassMeaning
CORE-SYS-0001500serverUnexpected internal error. Idempotent operations may be retried with backoff.
CORE-SYS-0002503serverA dependency (DB/Redis/queue) is temporarily unavailable. Retryable.
CORE-SYS-0003504serverTimed out. Retryable.
CORE-SYS-0004501serverEndpoint/feature not implemented.
CORE-REQ-0001400clientMalformed request (bad JSON, missing field).
CORE-REQ-0002422clientValidation failed; per-field errors in details[].
CORE-REQ-0003404clientResource does not exist (or is outside your workspace scope).
CORE-REQ-0004409clientState conflict (duplicate, precondition, in use).
CORE-REQ-0005409clientIdempotency key reused with a different body.
CORE-REQ-0006413clientBody exceeds the limit.
CORE-AUTH-0001401clientMissing or invalid credentials.
CORE-AUTH-0002403clientAuthenticated but not permitted.
CORE-RATE-0001429clientRate limited; honour Retry-After.
CORE-TENANT-0001404clientWorkspace could not be resolved.
CORE-TENANT-0002403clientWorkspace suspended.
CORE-TENANT-0003400clientA 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:

json
{ "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:

codeHTTP
unauthorized401
forbidden403
not_found404
parameter_invalid400
conflict409
rate_limit_exceeded429
internal_error500

The retry rule

SituationRetry?
429Yes — after waiting out Retry-After
500 · 502 · 503 · 504Yes — exponential backoff + jitter
408 (timeout)Yes
Other 4xxNo — 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.

Bu sayfa işine yaradı mı?