Errors

The API uses standard HTTP status codes and returns errors in JSON, always with the same shape.

Error format

{
  "statusCode": 403,
  "code": "AUTH_INSUFFICIENT_PERMISSIONS",
  "message": "Description of the error",
  "details": { },
  "timestamp": "2026-10-10T18:08:18.423Z",
  "path": "/api/v1/notification-preferences",
  "requestId": "101c888e-a926-451a-95db-9f62bf7bdc8b"
}

Field	Content
statusCode	The HTTP code.
code	Stable error code, meant for your integration to decide what to do (see below).
message	Readable description. In validation errors, the messages for each field are joined with ; .
details	Optional: extra information (for example, the duplicated field).
timestamp, path	When and on which route it happened.
requestId	Identifier of the request. Include it if you report a problem to support.

Common HTTP codes

HTTP	Usual code	Meaning
400	VALIDATION_FAILED / VALIDATION_INVALID_INPUT	Invalid request (malformed data or data that fails validation).
401	AUTH_TOKEN_INVALID	Not authenticated: missing, invalid or expired token, or invalid API Key.
402	SAAS_ACCOUNT_LOCKED	The Organization’s account is paused for payment (for example, an expired trial). details.reason gives the reason. See Multi-tenant.
403	AUTH_INSUFFICIENT_PERMISSIONS	No permission for the resource (also: API Key hourly limit exceeded, IP or domain not authorized, closed organization).
404	RESOURCE_NOT_FOUND	Resource not found.
409	RESOURCE_ALREADY_EXISTS	The record already exists (duplicated value).
429	RATE_LIMIT_EXCEEDED	Too many requests (see Rate limits).
500	SYSTEM_INTERNAL_ERROR	Internal server error.
503	SYSTEM_SERVICE_UNAVAILABLE	Service unavailable (for example, a suspended organization).

Some business errors carry a more specific code, for example INVOICE_ALREADY_PAID, SUBSCRIPTION_NOT_ACTIVE, TENANT_SUSPENDED or AUTH_INVALID_CREDENTIALS. Use the code, not the message text, to make decisions in your code.

Tip

On a 401, authenticate again to get a valid token.