Error codes
Every failure carries {code, message, hint, docs_url}. Branch on code. Codes are never renamed or reused; new ones may be added, so treat an unknown code as internal.
| Code | HTTP | FTP | SFTP status | Meaning |
|---|---|---|---|---|
auth_failed | 401 | 530 | auth refused | Missing or wrong credentials |
permission_denied | 403 | 550 | PERMISSION_DENIED (3) | Logged in, but not allowed |
not_found | 404 | 550 | NO_SUCH_FILE (2) | No such file, directory, user, or session |
already_exists | 409 | 550 | FAILURE (4) | The name is taken |
invalid_path | 400 | 553 | PERMISSION_DENIED (3) | The path leaves the root or is malformed |
invalid_command | 400 | 500 | BAD_MESSAGE (5) | Malformed command, packet, body, or config |
rate_limited | 429 | 421 | FAILURE (4) | A limit fired: ban, cap, timeout, drain |
quota_exceeded | 507 | 552 | FAILURE (4) | The write would exceed the user's quota |
tls_required | 426 | 534 | n/a | TLS is required for this |
internal | 500 | 451 | FAILURE (4) | Server-side fault |
FTP may use a protocol-specific number where an RFC requires one (for example 504 for an unknown HOST, 503 for HOST after USER); the code after the number is always one of the ten.
auth_failed
Credentials were missing or wrong, the password expired, the key is expired or revoked, the user may not log in under this FTP HOST, or (admin API, MCP) the token is wrong or not configured. All of these look the same on purpose. Repeated failures from one address lead to a ban (rate_limited).
permission_denied
The user lacks the permission bit for this path (r w d n m l), possibly because of a directory rule; a config-file user was changed through the API (edit the file instead); a WebDAV client tried to write (the gateway is read-only); or an active-mode PORT named another host or a port below 1024. The hint says which bit is missing.
not_found
The file, directory, user, or session does not exist. List the parent (MLSD, SFTP READDIR, GET /api/v1/files) or the collection (GET /api/v1/users, GET /api/v1/sessions).
already_exists
A create collided with an existing name: MKD, an exclusive SFTP open, SFTP RENAME onto an existing file (use posix-rename@openssh.com to replace), or a user name that is taken.
invalid_path
The path contains NUL, a .. that leaves the root (also when percent-encoded), a symlink that points outside, or a new symlink whose target is outside the root. The same request is refused identically on every protocol.
invalid_command
The request is malformed: unknown FTP verb, bad argument, oversized line or packet, unsupported SFTP extension, invalid JSON, unknown config key, weak password hash, unsupported SSH key option. The hint names the expected form; HELP, tools/list, and /api/v1/openapi.json list what is valid.
rate_limited
A protective limit fired: login ban, connection cap (global or per address), per-user session cap, too many open SFTP handles, too many concurrent admin requests, an idle or handshake timeout, or the server is draining for a restart. Wait and retry; operators tune these under [server].
quota_exceeded
The write (upload, SFTP write, or SETSTAT that grows a file) would exceed quota_bytes. The partial file is removed unless the client was extending an existing one (REST, APPE). Free space or raise the quota.
tls_required
The server requires TLS (require_tls), PROT was sent without AUTH TLS, CCC was attempted, active mode was combined with PROT P, or a TLS data connection did not resume the control session while require_session_reuse is on. Connect with AUTH TLS, PBSZ 0, PROT P, or use the implicit FTPS port.
internal
A server-side fault: disk error, unreadable TLS material, an S3 or LDAP server that is down or refusing access. Retry once; if it persists, the message and the daemon log name the cause.