Errors
Structured JSON errors — 4xx for request/access problems, 5xx for retryable platform failures.
Errors are returned as structured JSON. Treat 4xx as request or access problems, and 5xx
as retryable platform failures.
| Status | Meaning |
|---|---|
422 | Invalid request — malformed body, bad query parameters, or a body that fails the entity's unified schema validation. |
401 | Missing, malformed, or revoked API key. Check the authorization header. |
404 | Unknown accountId, or an entityType this account's platform does not expose. |
429 | The backing system's rate limit was reached. Retry with exponential backoff. |
5xx | Temporary LinkToAny or platform issue. Safe to retry idempotent reads; retry writes with the same externalId — it doubles as the idempotency key. |
SDK error classes
The Node.js SDK maps each status onto a typed error class. Retryable failures
(429, 5xx, network) retry automatically with exponential backoff honouring Retry-After
before anything throws.
| Error class | Status | Meaning |
|---|---|---|
AuthenticationError | 401 | Missing, malformed, or revoked API key. |
PermissionError | 403 | Key is valid but not scoped for this account or action. |
NotFoundError | 404 | Unknown accountId, or an entityType this account's platform does not expose. |
ValidationError | 400 / 422 | Request or write payload failed schema validation — see err.body. |
RateLimitError | 429 | Raised only after automatic retries are exhausted. |
ServerError | 5xx | Temporary LinkToAny or platform issue. Safe to retry idempotent reads. |
TimeoutError / ConnectionError | — | The request never completed — network failure or timeoutMs exceeded. |
Every error carries status, code, body, and requestId — include requestId when
escalating to support.