Error Codes

Voke returns a stable error envelope on every 4xx/5xx:

{
  "statusCode": 400,
  "message": "human-readable summary",
  "error": "Bad Request",
  "code": "DEVICE_TEMPLATE_SIGNAL_INVALID",
  "details": ["signals.0.bit: must be an integer >= 0"]
}

The code field is the stable machine-readable contract — prefer it over message when handling errors programmatically. details is optional and may be an array of strings or a structured object depending on the error source.

HTTP status codes follow the NestJS exception convention (400 = BadRequestException, 401 = UnauthorizedException, 403 = ForbiddenException, 404 = NotFoundException, 409 = ConflictException, 429 = TooManyRequestsException, 503 = ServiceUnavailableException, 500 = InternalServerErrorException).

Codes

Generic

Code	HTTP	Description
`BAD_REQUEST`	400	Generic bad request; used when no more-specific 400 code applies.
`VALIDATION_ERROR`	400	Request body or query DTO failed class-validator validation.
`INVALID_UUID`	400	A path or query parameter that must be a UUID v4 is malformed.
`NOT_FOUND`	404	Generic not-found fallback; used when no more-specific 404 code applies.
`CONFLICT`	409	Generic conflict (e.g. duplicate unique constraint) when no more-specific code applies.
`TOO_MANY_REQUESTS`	429	Rate limit exceeded.
`SERVICE_UNAVAILABLE`	503	A downstream dependency (MQTT broker, queue, external ESM) is temporarily unreachable.
`INTERNAL_SERVER_ERROR`	500	Unhandled server error.

Auth (`UNAUTHORIZED`, `FORBIDDEN`, permissions)

Code	HTTP	Description
`UNAUTHORIZED`	401	Request lacks a valid JWT or the session has expired.
`FORBIDDEN`	403	Authenticated but not allowed to perform this action.
`ORG_CONTEXT_REQUIRED`	403	The `x-org-id` header is missing; the endpoint requires an active org context.
`ORG_MEMBERSHIP_REQUIRED`	403	The authenticated user is not a member of the org specified in `x-org-id`.
`INSUFFICIENT_ORG_PERMISSIONS`	403	The user's role within the org does not grant permission for this operation.
`SUPER_ADMIN_REQUIRED`	403	The endpoint is restricted to platform super-admins.

Auth flow (`AUTH_`, `EMAIL_`, `ACCOUNT_*`)

Code	HTTP	Description
`INVALID_CREDENTIALS`	401	Email/password combination is incorrect during login.
`ACCOUNT_LOCKED`	403	Account has been temporarily locked after too many failed login attempts.
`EMAIL_ALREADY_REGISTERED`	409	Registration or invite-accept was attempted with an email that already has an account.

Invitations (`INVITATION_*`)

Code	HTTP	Description
`INVITATION_TOKEN_MISSING`	400	An invite-based endpoint was called without an invitation token in the request.
`INVITATION_NOT_FOUND`	404	No pending invitation exists for the supplied token.
`INVITATION_EXPIRED`	403	The invitation token exists but has passed its expiry date.
`INVITATION_ALREADY_ACCEPTED`	409	The invitation has already been accepted and cannot be used again.

Organizations (`ORGANIZATION_`, `MEMBER_`)

Code	HTTP	Description
`ORGANIZATION_NOT_FOUND`	404	No organization found for the given ID or slug.
`MEMBER_NOT_FOUND`	404	No membership record found for the specified user within the target organization.

Plants (`PLANT_*`)

Code	HTTP	Description
`PLANT_NOT_FOUND`	404	No plant found for the given ID within the org context.
`PLANT_ALREADY_EXISTS`	409	A plant with the same unique identifier already exists in the organization.
`PLANT_INVALID_STATE`	400	The requested operation is not valid for the plant's current state (e.g. provisioning vs. active).
`PLANT_NOT_LINKED_TO_ESM`	400	The plant has no `external_plant_id` and cannot participate in ESM trading sync.

Device templates (`DEVICE_TEMPLATE_*`)

Code	HTTP	Description
`DEVICE_TEMPLATE_NOT_FOUND`	404	No device template found for the given ID within the org context.
`DEVICE_TEMPLATE_IN_USE`	409	Cannot delete a device template that is currently assigned to one or more sub-devices.
`DEVICE_TEMPLATE_SIGNAL_INVALID`	400	A signal definition in the template body failed Zod validation (check `details` for field paths).
`DEVICE_TEMPLATE_ACTION_INVALID`	400	An action definition in the template body failed Zod validation (check `details` for field paths).
`DEVICE_TEMPLATE_SYSTEM_READONLY`	403	The template is a system-level template and cannot be modified or deleted by org users.
`DEVICE_TEMPLATE_WRONG_LEVEL`	400	A plant-level assignment referenced a template whose `level` is not `PLANT`.

Sub-devices (`SUB_DEVICE_*`)

Code	HTTP	Description
`SUB_DEVICE_NOT_FOUND`	404	No sub-device found for the given ID within the plant context.
`SUB_DEVICE_EXTERNAL_ID_TAKEN`	409	Another sub-device in the same plant already uses the requested `externalId`.
`SUB_DEVICE_EXTERNAL_ID_INVALID`	400	The provided `externalId` does not match the required format (short alphanumeric, e.g. `R1`, `M1`).

Commands (`COMMAND_*`)

Code	HTTP	Description
`COMMAND_ACTION_NOT_IN_TEMPLATE`	400	The requested action key is not defined in the sub-device's device template.
`COMMAND_PARAMS_INVALID`	400	The command payload does not satisfy the action's parameter schema in the device template.

API keys (`API_KEY_*`)

Code	HTTP	Description
`API_KEY_NOT_FOUND`	404	No API key found for the given ID, or the key has been revoked.

Trading / ESM (`TRADING_`, `ESM_`)

Code	HTTP	Description
`TRADING_NOT_ENABLED`	400	The organization has not enabled the trading partner integration (reserved).
`TRADING_CONFIG_INCOMPLETE`	400	The trading partner configuration exists but is missing required credentials (client ID / secret / URL).
`ESM_NOT_CONFIGURED`	400	No ESM endpoint URL has been configured for this organization.
`ESM_URL_NOT_ALLOWED`	400	The provided ESM URL does not match the allowlist of permitted ESM host patterns (reserved).

Voke ESM (`VOKE_ESM_*`)

Code	HTTP	Description
`VOKE_ESM_DISABLED`	—	Startup-only guard thrown when `VOKE_ESM_ENABLED` is absent in production. Never emitted on HTTP responses; only appears in API boot logs.

Error Codes

On this page