remo · documentation
AI RU

Error codes and what to do

What a code means, who returns it, and which action by the user or integration resolves it.

Status: available updated 2026-11-06

How to read a code

A message always has two parts: what happened and what to do. The code is the machine name of the same situation.

Example response

{ "error": "SCOPE_REQUIRED", "message": "this token does not carry board.edit" }

The body is always the same shape: a machine-readable error and a human message. The message says what is wrong without leaking secrets or room text.

What to do with a code

Response Action
401 refresh the session or the token; repeating as-is will not help
403 obtain the permission or scope; a retry will not help
403 UNCLAIMED the room has no owner: it needs a claim, not access
404 check the identifier and your access to the room
409 STALE re-read the room, update ifVersion, retry
409 JOB_NOT_FOUND start the export job again
422 fix the input; the field is named in the message
503 NOT_PERSISTED retry with the same Idempotency-Key

Access

Code Status Meaning Action
AUTH_REQUIRED 401 there is no session sign in
ACCOUNT_REQUIRED 403 there is no account, and the action requires permissions sign in or use an integration token
FORBIDDEN 403 the role does not give the required permission request the role from the room owner
RESOURCE_NOT_AVAILABLE 404 the room does not exist or is not visible check the link and access
SCOPE_REQUIRED 403 the integration token has no required scope issue a token with the required scope
INTEGRATION_TOKEN_UNKNOWN 401 the token does not exist check the token value
INTEGRATION_TOKEN_REVOKED 401 the token is revoked issue a new one
INTEGRATION_TOKEN_EXPIRED 401 the token has expired issue a new one
PASSWORD_REQUIRED 401 the link has a password enter the password
LINK_INACTIVE 404 the link is disabled or has expired enable the link or request a new one
UNCLAIMED 403 the room has no owner claim the room or assign an owner
CLAIM_REJECTED 403 the claim token is wrong or missing, when the room has one open the link with the right token
ALREADY_CLAIMED 409 the room already has an owner work through the owner; a second claim is refused
ORG_REQUIRED 409 the account has no organisation create an organisation and repeat the claim
EMAIL_MISMATCH 422 the invitation is for another email sign in with the invited account
BACKUP_REQUIRED 403 replacing the discussion needs the backup grant request board.backup

A room without an owner

GET /boards/:id/access for such a room answers 200 with allowed: false, reason: "UNCLAIMED" and an empty capability list. That is enough to show the claim screen, but not the content: every other route except the claim answers 403 UNCLAIMED, the socket refuses the connection, and the room is in neither the room list nor the trash.

A claim is POST /boards/:id/claim with an optional {token}. The room is assigned to the signed-in person, the archive mark is cleared, and the organisation and team come from the account; without an organisation or a team the answer is 409 ORG_REQUIRED or 409 TEAM_REQUIRED. Ordinary roles and the public link apply after the claim.

Commands and writes

Code Status Meaning Action
BAD_INPUT 422 the input failed validation fix the field named in the message
IDEMPOTENCY_KEY_REQUIRED 400 Idempotency-Key is missing send the header
STALE 409 the room changed since the version was read re-read and retry
NOT_PERSISTED 503 the change is in memory but not written retry with the same key
OBJECT_NOT_FOUND 404 the object does not exist re-read the room
CONNECTOR_EXISTS 409 the pair already has a connector change the existing one
SELF_LOOP 422 an object is connected to itself choose another end
OBJECT_LOCKED 409 the object is locked the author or a manager releases it
LOCKED_BY_OTHER 409 the lock belongs to somebody else ask the author or a manager to release it
COMMENT_FORBIDDEN 403 the role cannot write in the discussion request board.comment
COMMENT_BODY_REQUIRED 422 the comment is empty or too long enter 1 to 4000 characters
COMMENT_ANCHOR_REQUIRED 422 the thread has no object or point select an object or a place in the room
THREAD_NOT_FOUND 404 the thread is missing or in another room reload the list
COMMENT_NOT_FOUND 404 the message is missing reload the thread

Profile, organisation and room

Code Status What it means What to do
HANDLE_TAKEN 409 the handle is taken choose another
BAD_HANDLE 422 the handle breaks the rules 3–32 characters, Latin letters, digits, ., -, _; start and end with a letter or digit
HANDLE_TOO_SHORT / HANDLE_TOO_LONG 422 the handle is outside 3–32 fix the length
HANDLE_RESERVED 422 a reserved handle choose another
NAME_REQUIRED / NAME_TOO_LONG 422 the name is empty or longer than 80 enter a name of 1–80 characters
ICON_TOO_LONG / BAD_ICON 422 the emoji is too long or contains control characters choose one emoji
EMAIL_TAKEN 409 the email is already registered sign in or recover access
WEAK_PASSWORD 422 the password is shorter than 10 characters choose a longer password
RATE_LIMITED 429 too many attempts wait and retry
ORG_NAME_REQUIRED 422 the organisation has no name enter a name
TEAM_NAME_REQUIRED / TEAM_NAME_TAKEN 422/409 the team name is empty or taken choose another name
TEAM_IN_USE 409 rooms or grants refer to the team reassign them first
TEAM_REQUIRED 409/422 the organisation has no team: 409 on a claim, 422 when creating a room create a team
ALREADY_ARCHIVED / NOT_ARCHIVED 409 the room is already in the trash or already out of it re-read the state
BOARD_CREATE_FORBIDDEN 403 the role cannot create rooms ask for active organisation membership

Export

Code Status Meaning Action
BAD_SCOPE 422 unknown scope select selection, frame or board
BAD_FORMAT 422 unknown job format select png or pdf; a backup is a separate request
JOB_NOT_FOUND 409 the export job has expired start the export again

Where to go next

Export and backup — what export and backup require. Room access — claiming a room without an owner and roles.