Fehlercodes
Jede Fehlerantwort verwendet den Umschlag { "error": { "code", "message", "details"? } }. code ist ein stabiler, maschinell geprüfter Bezeichner — verzweigen Sie darauf, nicht auf message (ein menschlicher Satz, der sich ändern kann). Jede Antwort trägt zudem einen X-Request-ID-Header; geben Sie ihn bei einer Störungsmeldung an. Die häufigsten übergreifenden Codes:
| Code | HTTP | Wann er auftritt |
|---|---|---|
VALIDATION_ERROR | 422 | Request body or query params failed Zod validation; details lists the offending paths. |
UNAUTHORIZED | 401 | No valid credential (missing/expired JWT or API key). |
INVALID_CREDENTIALS | 401 | Login failed — email/password did not match. |
INVALID_TOKEN | 401 | A one-time or scoped token (invite, verify, onboarding, refresh) is malformed, expired, or already used. |
FORBIDDEN | 403 | Authenticated, but the principal’s role lacks permission for this action (RBAC). |
NOT_FOUND | 404 | The resource does not exist, or is not visible to the caller under row-level security. |
CONFLICT | 409 | The request conflicts with current state (e.g. a duplicate unique value). |
INVALID_STATE | 422 | The target is not in a state that permits this transition. |
RATE_LIMITED | 429 | The per-plan sliding-window rate limit was exceeded; see the Retry-After header. |
ENTITLEMENT_EXCEEDED | 422 | A plan ceiling (products, seats, storage) is already at its limit; details names the entitlement. Only returned when entitlement enforcement is enabled. |
PLAN_UPGRADE_REQUIRED | 402 | The requested capability is not included in the organisation's plan; details names the entitlement. Only returned when entitlement enforcement is enabled. |
GONE | 410 | The resource once existed but has been withdrawn or offboarded. |
ORG_SUSPENDED | 403 | The organisation is suspended — reads and DSAR export stay open, mutations are frozen. |
INTERNAL_ERROR | 500 | An unexpected server error; internals are never leaked to the client. |
SANDBOX_READONLY | 403 | A sandbox API key attempted a mutating request; sandbox keys are read-only. |
INSUFFICIENT_SCOPE | 403 | The API key lacks the *:read/*:write scope this verb requires. |
SELECTION_TOO_LARGE | 422 | A bulk selection (e.g. enrichment ids) exceeds the per-job cap. |
CONDITION_NOT_MET | 422 | A workflow transition’s data condition evaluated false (fail-closed). |
TRANSFORM_FAILED | 422 | An onboarding mapping transform failed; approve is all-or-nothing with row-addressed details. |
GLN_INVALID | 422 | A supplied GLN failed check-digit or ownership validation. |
UNKNOWN_FRAMEWORK | 400 | A compliance framework code is not registered. |
GDSN_NO_CONNECTION | 400 | A GDSN publish was attempted with no active data-pool connection. |
SSO_FAILED | 401 | The SAML/OIDC assertion could not be validated or mapped to an org connection. |