IMAP Response Codes
Extracted elements (23)
AUTHENTICATIONFAILED is semantically equivalent to sending no response code, except that its presence tells the client the failure was not due to a transient condition like UNAVAILABLE, so there is no point in retrying the same credentials later. This distinction drives the motivation for named codes over no-code responses.
This document names machine-readable response codes for IMAP errors that were previously described only in human-readable English text. The goal is better interoperation and error reporting, allowing clients to distinguish error categories (e.g., server-side temporary failure vs. bad password) without attempting to parse free-form text.
If a server sends OVERQUOTA but does not support the IMAP QUOTA extension defined by RFC 2087, the client knows a quota exists but cannot determine what it is. Implementors should be aware of this informational asymmetry.
ALREADYEXISTS indicates the operation attempts to create something that already exists, such as CREATE or RENAME targeting a mailbox name already in use. NONEXISTENT indicates the operation attempts to delete or rename something that does not exist.
AUTHENTICATIONFAILED indicates authentication failed for a reason the server is unwilling to elaborate on, typically including unknown user or bad password. Its presence lets the client distinguish this from a temporary UNAVAILABLE failure.
AUTHORIZATIONFAILED indicates authentication succeeded for the authentication identity, but the server will not allow that identity to act as the requested authorization identity. This is only applicable when authentication and authorization identities differ.
CANNOT indicates the operation violates some invariant of the server and can never succeed, as opposed to transient failures. For example, creating a mailbox name with adjacent slashes that the server does not support.
CONTACTADMIN indicates the user should contact the system administrator or support desk. It can accompany an OK response, suggesting a non-fatal condition requiring administrative attention.
CORRUPTION indicates the server discovered that some relevant data (e.g., the mailbox) are corrupt. The response code does not identify what is corrupt, but the server should log that information internally.
EXPIRED indicates that access is no longer permitted using the supplied passphrase, either because the passphrase has expired or the server no longer has the necessary data. The client or user should obtain a new passphrase.
EXPUNGEISSUED indicates another session has issued an EXPUNGE for the same mailbox. The client may want to issue NOOP soon; RFC 2180 discusses multi-access mailbox behavior in depth.
INUSE indicates an operation could not be carried out because an exclusive lock is held by someone else, or the operation involves deleting a resource another session is using (typically a mailbox). The operation may succeed if retried later.
LIMIT indicates the operation ran up against an implementation limit, such as the maximum number of flags on a single message or the total number of flags used in a mailbox.
NOPERM indicates the access control system (e.g., ACL per RFC 4314) does not permit the user to carry out the requested operation, such as selecting or creating a mailbox.
OVERQUOTA indicates the user would be over quota after the requested operation. It may accompany OK (soft quota exceeded) or NO (hard quota exceeded). If the server sends OVERQUOTA but does not support the QUOTA extension (RFC 2087), the client cannot determine the quota limit.
PRIVACYREQUIRED indicates an operation is not permitted due to a lack of privacy. If TLS is not in use, the client could try STARTTLS and then repeat the operation.
SERVERBUG indicates the server encountered a bug in itself or violated one of its own invariants. CLIENTBUG indicates the server detected a bug in the client and may accompany OK, NO, or BAD depending on the nature of the bug.
UNAVAILABLE indicates a temporary failure because a subsystem is down (e.g., an LDAP or RADIUS server used for authentication). The operation may succeed if the client tries again later.
Extensions to the IMAP Response Codes registry require a registration request to IANA forwarded to a Designated Expert. After 30 days of community review on the IMAP Extensions mailing list or a successful IETF Last Call, the expert approves or denies the request. Registrations may not be deleted; obsolete codes are marked 'obsolete' in the registry.
IANA created the IMAP Response Codes registry, initially populated with codes from RFC 2060, 2221, 3501, 3516, 4315, 4467, 4469, 4551, 4978, 5162, 5182, 5255, 5257, 5259, 5267, 5464, 5465, 5466, and 5530. Entries marked with a status description (e.g., 'obsolete') are NOT RECOMMENDED for widespread use.
Machine-readable response codes are easier to parse than human-readable text and can amplify information leaks. For example, returning different responses when a mailbox does not exist versus when the user lacks the 'l' right (right to know the mailbox exists) could inadvertently expose ACL information to well-behaved clients that forward the codes to users.
Revealing information about a passphrase to unauthenticated IMAP clients is harmful. Server authors are encouraged to be particularly careful with NOPERM and authentication-related response codes.
Section 4 extends the IMAP resp-text-code non-terminal (RFC 3501) via ABNF to include the 16 new response code tokens: UNAVAILABLE, AUTHENTICATIONFAILED, AUTHORIZATIONFAILED, EXPIRED, PRIVACYREQUIRED, CONTACTADMIN, NOPERM, INUSE, EXPUNGEISSUED, CORRUPTION, SERVERBUG, CLIENTBUG, CANNOT, LIMIT, OVERQUOTA, ALREADYEXISTS, and NONEXISTENT. All alphabetic characters in these tokens are case-insensitive.