DocsReferenceError codes

Error codes

Every error WBSKT returns carries a code to branch on and a traceId to quote when you ask for help. Codes never change meaning; new ones are only added.

404 application/problem+json
{
  "status": 404,
  "title": "Not Found",
  "detail": "No such client.",
  "code": "CLIENT_NOT_FOUND",
  "traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00"
}

A 400 from validation also carries errors, each field with its messages. A 429 or 503 carries a Retry-After header: wait that many seconds, then try again. The WebSocket has its own close codes.

126 codes

Any request13 codes

CodeStatusMeans, and what to do
VALIDATION_FAILED400A field is missing or malformed. errors lists each field and its messages.
PAGE_CURSOR_INVALID400The cursor isn't one a list gave you. Start again from the first page.
IDEMPOTENCY_KEY_INVALID400The Idempotency-Key header is empty or too long.
TIME_RANGE_INVALID400from is after to, or one of them isn't a time.
TIME_RANGE_TOO_LONG400The range is longer than this list allows. Ask for a shorter one.
AUTH_UNAUTHORIZED401You aren't signed in, or the token expired. Sign in again.
AUTH_FORBIDDEN403Signed in, but not allowed to do this.
NOT_FOUND404Nothing lives at that address.
RATE_LIMITED429Too many requests. Wait the seconds in Retry-After.
INTERNAL_ERROR500Our fault. Quote the traceId on GitHub and we'll look.
UNAVAILABLE503Something WBSKT depends on is down and nothing was done. Retry after Retry-After.
EVENT_BUS_UNAVAILABLE503The message bus is down, so the command wasn't sent. Retry after Retry-After.
AUTH_UNAVAILABLE503Sign-in is briefly unavailable. Retry in a moment.

Board connection10 codes

CodeStatusMeans, and what to do
REGISTRATION_PIN_REQUIRED400Registration was sent without a PIN.
POLICY_LIMIT_REACHED400Registration refused: the account is at its plan's client limit.
SOCKET_PROTOCOL_UNSUPPORTED400The WebSocket didn't ask for the wbskt.v1 subprotocol.
SOCKET_UPGRADE_REQUIRED400A plain HTTP request reached /ws. Open a WebSocket instead.
CLIENT_NOT_REGISTERED401The client is pending approval, or was revoked or rejected. Keep retrying; it connects once approved.
CLIENT_UNAUTHORIZED401Its secret is no longer valid (deleted or rotated). Clear stored credentials and register again.
CLIENT_TOKEN_INVALID401The socket's access token is missing, expired or wrong. Log in again for a new one.
CLIENT_REVOKED403Refused at connect: the client lost access after its token was issued.
POLICY_DISABLED403The policy for that PIN is switched off. Enable it in the console.
POLICY_FULL409The policy has reached its own client limit. Raise the limit or use another policy.

Clients and commands17 codes

CodeStatusMeans, and what to do
CLIENT_NAME_INVALID400The name is empty or too long.
CLIENT_REFS_INVALID400A list of client references is empty, too long or holds something that isn't a reference.
CLIENT_TAG_INVALID400A tag is empty, too long or uses characters tags can't have.
CLIENT_TAGS_TOO_MANY400A client can carry only so many tags. Remove some first.
CLIENT_UPDATE_EMPTY400The update named no field to change.
COMMAND_TYPE_INVALID400The command type is empty or too long.
COMMAND_TYPE_RESERVED400The command type starts with sys. or is otherwise reserved.
COMMAND_PAYLOAD_TOO_LARGE400The command is over 64 KB.
COMMAND_EXPIRY_INVALID400The expiry is in the past or further out than a command can wait.
COMMAND_STATUS_INVALID400The status filter isn't one commands can have.
DIRECTION_INVALID400The direction filter must be inbound or outbound.
EVENT_LOG_SEARCH_TOO_LONG400The activity search text is too long.
DELETED_WINDOW_INVALID400The window for recently deleted clients is out of range.
CLIENT_NOT_FOUND404No client with that reference in this workspace.
COMMAND_NOT_QUEUED404There's no queued command with that id; it was delivered, expired or cancelled.
CLIENT_INACTIVE409The client is paused or revoked, so it can't take commands.
CLIENT_UPDATE_ERROR500The change couldn't be saved. Try again; quote the traceId if it keeps failing.

Firmware updates and readings10 codes

CodeStatusMeans, and what to do
OTA_URL_INVALID400Firmware links must be https.
OTA_SHA256_INVALID400The SHA-256 must be 64 hex characters.
OTA_SIZE_INVALID400The firmware size must be a positive number of bytes.
OTA_VERSION_INVALID400The version is empty or too long.
OTA_NOT_SUPPORTED409The client didn't list ota in its capabilities.
READINGS_NAME_REQUIRED400Say which state variable to chart with name.
READINGS_NAME_INVALID400The variable name is too long or malformed.
READINGS_BUCKET_INVALID400The bucket size isn't one readings can be grouped by.
READINGS_RANGE_TOO_LARGE400The time range is longer than readings are kept for.
READINGS_TOO_MANY_BUCKETS400The range and bucket size make too many points. Use bigger buckets.

Policies and templates8 codes

CodeStatusMeans, and what to do
POLICY_NAME_REQUIRED400A policy needs a name.
POLICY_LIMIT_CONFLICT400The client limit is below the number of clients already in the policy.
TEMPLATE_NAME_INVALID400The template name is empty or too long.
TEMPLATE_TYPE_INVALID400The template's message type is empty or too long.
TEMPLATE_TYPE_RESERVED400The template's message type is reserved, like sys. types.
TEMPLATE_PAYLOAD_INVALID400The payload isn't valid JSON, or it's over 64 KB.
POLICY_NOT_FOUND404No policy with that reference in this workspace.
TEMPLATE_NOT_FOUND404No template with that reference in this workspace.

Workflows and runs15 codes

CodeStatusMeans, and what to do
WORKFLOW_VALIDATION_FAILED400The workflow has problems: a missing trigger, an unconnected port or a bad setting. The response lists each one.
WORKFLOW_DRAFT_INVALID400The draft can't be read as a workflow.
TEST_RUN_TRIGGER_REQUIRED400A test run needs a trigger payload to start from.
TEST_RUN_TRIGGER_NOT_FOUND400The test run names a trigger the draft doesn't have.
WORKFLOW_NOT_FOUND404No workflow with that reference in this workspace.
WORKFLOW_DRAFT_NOT_FOUND404The workflow has no draft. Start one from the published version.
WORKFLOW_VERSION_NOT_FOUND404The workflow has no version with that number.
RUN_NOT_FOUND404No run with that reference in this workspace.
VARIABLE_NOT_FOUND404The shared variable hasn't been set yet.
WORKFLOW_ALREADY_ENABLED409It's already on.
WORKFLOW_DEPRECATED409The workflow is deprecated and takes no new runs. Reinstate it first.
WORKFLOW_DELETED409The workflow was deleted. Restore it before changing it.
WORKFLOW_REF_TAKEN409Another workflow in the workspace already uses that reference.
RUN_NOT_CANCELLABLE409The run has already finished.
WORKFLOW_DEFINITION_UNREADABLE500A stored version can't be read. Quote the traceId on GitHub.

Integrations7 codes

CodeStatusMeans, and what to do
INTEGRATION_NAME_INVALID400The name is empty or too long.
INTEGRATION_TYPE_INVALID400That isn't a kind of integration WBSKT has.
INTEGRATION_PRESET_INVALID400The HTTP auth preset is unknown, or its fields don't match it.
INTEGRATION_SECRET_UNREADABLE400A stored secret can't be read any more. Enter it again.
INTEGRATION_NOT_FOUND404No integration with that reference in this workspace.
INTEGRATION_NAME_TAKEN409Another integration in the workspace has that name.
INTEGRATIONS_UNAVAILABLE503The integration service is down and nothing was sent. Retry in a moment.

Sign-in and account23 codes

CodeStatusMeans, and what to do
PASSWORD_BREACHED400That password has appeared in a data breach. Choose another.
AUTH_CURRENT_PASSWORD_INVALID400The current password you typed is wrong.
AUTH_OPERATION_REJECTED400The request couldn't be completed as asked. Check the details and try again.
RESET_TOKEN_INVALID400The password reset link has expired or was already used. Ask for a new one.
VERIFICATION_TOKEN_INVALID400The email link has expired or was already used. Ask for a new one.
EMAIL_CHANGE_TOKEN_INVALID400The link to confirm a new email has expired or was already used.
EMAIL_UNCHANGED400That's already your email.
ACCOUNT_NO_CHANGES400The update named nothing to change.
USERNAME_CHANGED_RECENTLY400You changed your username a short while ago. Wait before changing it again.
USERNAME_RESERVED400That username is reserved. Pick another.
AUTH_INVALID_CREDENTIALS401Wrong email or password.
AUTH_INVALID_TOKEN401The token is malformed or signed by someone else. Sign in again.
AUTH_TOKEN_INACTIVE401The session was signed out or replaced. Sign in again.
AUTH_USER_INACTIVE401The account is suspended. Ask an admin of your account.
AUTH_USER_NOT_FOUND401The account behind this token no longer exists.
AUTH_ACCOUNT_LOCKED403Too many failed sign-ins. Wait, or reset your password.
AUTH_NOT_FOUND404Nothing matches that sign-in record.
AUTH_SESSION_NOT_FOUND404That session was already signed out.
USERNAME_TAKEN409Someone already uses that username.
AUTH_USERNAME_CONFLICT409Someone took that username at the same moment. Try another.
EMAIL_CHANGE_CONFLICT409Another account already uses that email.
ACCOUNT_SOLE_ADMINISTRATOR409You're the only admin somewhere. Make someone else an admin before deleting your account.
ACCOUNT_DELETE_RETRY409Deleting the account was interrupted. Send the request again.

Workspaces, members and roles23 codes

CodeStatusMeans, and what to do
INVITATION_INVALID400The invite has expired, was revoked or was already used.
WORKSPACE_OWNER_PROTECTED400The owner can't be removed. Transfer ownership first.
CANNOT_REMOVE_SELF400You can't remove yourself this way. Leave the workspace instead.
AUTH_CANNOT_SUSPEND_SELF400You can't suspend your own account.
MEMBER_UPDATE_EMPTY400The update named nothing to change for that member.
TENANT_REQUIRED400Say which account the request is for.
WORKSPACE_UNAUTHENTICATED401The request reached a workspace without a signed-in user. Sign in again.
WORKSPACE_FORBIDDEN403You aren't a member of that workspace, or it doesn't exist. We don't say which.
WORKSPACE_NOT_FOUND403Same answer as above, from the sign-in side: not a workspace you can open.
WORKSPACE_UNAUTHORIZED403Your membership doesn't cover this workspace any more.
PERMISSION_UNAUTHORIZED403You're a member but lack the permission. Ask an admin for a role that has it.
TENANT_NOT_FOUND403Not an account you belong to.
ROLE_NOT_FOUND403No role with that reference in your account.
GROUP_NOT_FOUND403No group with that reference in your account.
USER_NOT_FOUND404No such person in your account.
AUTH_ALREADY_MEMBER409That person is already in the workspace.
ROLE_NAME_TAKEN409Another role already has that name.
AUTH_ROLE_CONFLICT409The role was changed by someone else at the same time. Reload and try again.
AUTH_GROUP_CONFLICT409The group was changed by someone else at the same time. Reload and try again.
TENANT_SOLE_ADMINISTRATOR409You're the account's only admin. Make someone else an admin first.
TENANT_LEAVE_LAST409This is the only account you belong to, so you can't leave it.
TENANT_LEAVE_SOLE_MEMBER409You're the account's only member. Delete the account instead of leaving it.
WORKSPACE_RESOLVE_ERROR500We couldn't check your membership just then. Try again.

Plans and limits

Reaching a plan's limit slows or pauses things. It never charges you. Running out of clients shows up as POLICY_LIMIT_REACHED when a board registers. The codes for running out of credits or messages arrive with billing; see what happens at a limit.