Error codes
Ghoti answers a failed command with a short code instead of a message, which keeps every response small.
The authoritative list is internal/errs/README.md. The server embeds that file at compile time and reads its codes from it, so the code and the list can't drift apart. This page is a copy of it. If they ever disagree, the file in the repository wins.
Format#
An error is e, three characters for the slot, and three digits for the code. For slot 135 and error 006:
< e135006
Errors that aren't about a specific slot, such as a parse error, use xxx as the slot:
< exxx001
An error can carry an argument after the code. In a cluster, a follower answers with 000 followed by the leader's node ID, so the client knows which node to contact:
< exxx000node1
Summary#
| Code | Name | Closes connection | HTTP status |
|---|---|---|---|
000 | NOT_LEADER | No | 503 |
001 | PARSE_ERROR | No | 400 |
002 | WRONG_USER | Yes | Not applicable |
003 | WRONG_PASS | Yes | Not applicable |
004 | WRONG_LOGIN | Yes | Not applicable (401 for bad Basic Auth) |
005 | MISSING_SLOT | No | 404 |
006 | WRITE_PERMISSION | No | 403 |
007 | WRITE_FAILED | No | 400 |
008 | READ_PERMISSION | No | 403 |
009 | WRONG_FORMAT | Reserved, not returned | Not applicable |
010 | UNSUPPORTED_COMMAND | No | Not applicable |
000: NOT_LEADER#
This node is not the leader. Send the command to the leader node.
In cluster mode only the leader can be used to read and write. A follower answers every command with this error, followed by the name of the leader node:
< exxx000nodeA
Here nodeA is the node to contact. How the client maps that name to an address depends on how the cluster and the client were set up. See Routing traffic to the leader.
001: PARSE_ERROR#
The message couldn't be parsed: it doesn't follow the protocol. The cases that produce it are:
- The message is not terminated correctly for the transport in use: a missing
\nonstandard, or a missing\r\nontelnet. - The message is shorter than 4 bytes (
qexcepted). - The message is longer than 40 bytes, not counting the terminator. This is measured in bytes, so a value with multi-byte characters reaches the limit sooner than its character count suggests.
- The command byte is not a supported command.
- For commands that address a slot, the three bytes after the command are not a decimal number.
This error is never tied to a slot, so it is always exxx001.
002: WRONG_USER#
The username is too short or contains invalid characters: it is shorter than 4 bytes, or doesn't match ^[a-zA-Z][a-zA-Z0-9_]*$ (a letter, then letters, numbers or underscores).
The connection is closed after this error.
003: WRONG_PASS#
The password is too short: it is shorter than 4 bytes, or the username set before it was invalid.
The connection is closed after this error.
004: WRONG_LOGIN#
No configured user matches the username and password sent.
The connection is closed after this error.
005: MISSING_SLOT#
The slot addressed by the command is not configured. The slot number is valid and in range, but no slot with that number is defined in the configuration. Unlike the login errors, this response carries the requested slot number rather than xxx, for example e999005.
A slot whose definition is invalid is ignored at startup, so it also answers 005. See Slot reference.
006: WRITE_PERMISSION#
The logged-in user doesn't have permission to write this slot. If no user is logged in, the slot doesn't allow anonymous writes.
Token bucket and leaky bucket slots can't be written at all, so every write to them gets this error.
007: WRITE_FAILED#
The write was allowed, but the slot rejected it. Currently this happens when:
- On a
timeout_memoryslot, the writing connection is not the owner and the owner's timeout hasn't expired yet. - On an
atomicortickerslot, the value written is not a non-negative decimal integer.
This is not a permission error: 006 means the user may not write the slot at all, while 007 means the write was allowed but the slot rejected it.
008: READ_PERMISSION#
The logged-in user doesn't have permission to read this slot. If no user is logged in, the slot doesn't allow anonymous reads. s and d need read permission too.
009: WRONG_FORMAT#
The message doesn't have the right format.
This code is reserved and not returned by the server: malformed messages are reported as 001. It is kept so the code stays stable if the two cases are ever separated.
010: UNSUPPORTED_COMMAND#
The command is not supported by this slot. s (subscribe) and d (deregister) only work on slots that manage a group of clients, such as multicast slots. Sending them to any other kind of slot returns this error.