En informatique, le code d'état WebSocket permet de déterminer le résultat d'une connexion ou d'indiquer une erreur. Ce code numérique est destiné aux traitements automatiques par les applications de WebSocket. Ces codes d'état ont été définis par la RFC 6455[1]. Ils ont été étendus par l'IANA[2].
Certains codes ne sont pas encore utilisés, mais sont prévus pour une utilisation future.
Codes d'état
Il est théoriquement possible d'envoyer un code d'état entre 0 et 65535, mais la RFC n'autorise que les codes entre 1000 et 4999.
Légende des conventions de couleurs et de style
Les codes affichés sur fond clair (gris ou blanc) sont assignés, normalisés et peuvent être utilisés comme code d'état dans une trame de contrôle de fermeture.
Les codes affichés sur fond bleu sont assignés et normalisés, mais réservés à un usage interne : Ils ne doivent pas être envoyés comme code d'état dans une trame de contrôle de fermeture. Ils sont conçus pour identifier une erreur dans les applications attendant un code d'état, alors qu'aucun code d'état n'était réellement présent.
Les codes affichés sur fond rouge ne sont pas encore assignés officiellement. Ils ne doivent pas être utilisés. Une signification spécifique pourrait être définie à l'avenir.
Les codes affichés sur fond jaune sont assignés, mais non normalisés et donc non interopérables. Officiellement, il n'est pas précisé à quel usage ces codes sont destinés : à usage interne et/ou à être envoyé.
Les codes affichés sur fond cyan ont été assigné par une autre autorité, référez-vous à la section correspondante.
Codes de la RFC (1000 à 2999)
Les codes d'état entre 1000 et 2999 sont ou seront définis par le protocole WebSocket, ses révisions et ses extensions.
Codes commençant par 1 ou 2
Code
Signification
Description
1000
Normal Closure
Indique une fermeture normale, ce qui signifie que le but pour lequel la connexion a été établie a été rempli.
1001
Going Away
Indique qu'une application s'en va, comme un serveur qui tombe en panne ou un navigateur qui quitte une page.
1002
Protocol Error
Indique qu'une application met fin à la connexion en raison d'une erreur de protocole.
1003
Unsupported Data
Indique qu'une application met fin à la connexion parce qu'elle a reçu un type de donnée qu'elle ne peut pas accepter. Par exemple, une application qui ne comprend que des données textes, peut envoyer ceci si elle reçoit un message binaire (si le Opcode est 2).
À usage interne : Aucun code d'état n'était réellement présent.
Une trame de contrôle de fermeture a été reçue, mais aucun code n'était présent (Payload len = 0).
1006
Abnormal Closure
À usage interne : La connexion a été fermée de manière anormale, par exemple sans envoyer ni recevoir de trame de contrôle de fermeture.
1007
Invalid Frame Payload Data
Indique qu'une application met fin à la connexion parce qu'elle a reçu des données dans un message qui n'étaient pas cohérentes avec le type du message, par exemple, une séquence UTF-8 interdite dans un message texte.
1008
Policy Violation
Indique qu'une application met fin à la connexion car elle a reçu un message qui viole ses règles. Il s'agit d'un code d'état générique qui peut être renvoyé lorsqu'il n'y a aucun code d'état plus approprié, ou s'il est nécessaire de masquer des détails spécifiques à propos des règles.
1009
Message Too Big
Indique qu'une application met fin à la connexion car elle a reçu un message trop volumineux pour être traité.
1010
Mandatory Ext.
Indique qu'une application cliente met fin à la connexion car elle s'attendait à ce que le serveur négocie une ou plusieurs extensions, mais le serveur ne les a pas renvoyées dans le message de réponse de la poignée de main WebSocket. La liste des extensions qui sont nécessaires devrait apparaître dans la raison de fermer la connexion. Ce code d'état ne devrait pas être utilisé par l'application serveur, car elle devrait faire échouer la poignée de main WebSocket à la place.
1011
Internal Error
Indique qu'une application[3] met fin à la connexion, car elle a rencontré une condition inattendue qui l'a empêché de répondre à la demande.
1012–1014
(Unassigned)
Non assignés par la RFC, mais ces codes ont été assignés par l'IANA. Ils sont détaillés ci-dessous.
1015
TLS handshake
À usage interne : La connexion a été fermée en raison d'un échec de l'établissement d'une liaison TLS (par exemple, le certificat du serveur n'a pas pu être vérifié).
1016–2999
Unassigned
Non assignés.
Codes IANA (1012 à 1014 et 3000 à 3999)
Les codes d'état compris entre 3000 et 3999 sont destinés à une utilisation par les bibliothèques, les frameworks et les applications. Ces codes d'état sont enregistrés directement auprès de l'IANA, selon la procédure d'inscription du premier arrivé, premier servi. Ces codes ne sont pas définis par le protocole WebSocket.
Codes commençant par 3 (et codes de 1012 à 1014)
Code
Raison
Signification
1012
Service Restart
Indique que l'application serveur est redémarrée. L'application cliente peut se reconnecter, mais si elle choisit de le faire, elle devrait se reconnecter en utilisant un délai aléatoire (par exemple, de 5 à 30 secondes)[4].
Ce n'est pas précisé officiellement, mais l'application cliente peut augmenter ce délai si l'utilisateur ne fait aucune action (ou il peut être pertinent de se reconnecter immédiatement).
1013
Try Again Later
Indique que l'application serveur subit une surcharge. Une application cliente peut présenter une alerte à l'utilisateur. Elle ne doit se reconnecter que sur une adresse IP différente (lorsqu'il y en a plusieurs) ou sur une action de l'utilisateur[4].
1014
Bad Gateway ou Proxy Error
Le serveur agissait en tant que passerelle ou proxy et a reçu une réponse non valide du serveur distant (similaire au code HTTP 502)[5].
Contrairement au HTTP, la communication est bi-directionnelle, mais il n'est pas précisé officiellement si un client agissant en tant que passerelle ou un proxy peut également utiliser ce code.
3000
Unauthorized
Indique qu'une application met fin à la connexion en raison d'une erreur d'autorisation.
3001–3999
Unassigned
Non assignés.
Codes à usage privé (4000 à 4999)
Les codes d'état compris entre 4000 et 4999 sont assignés à un usage privé et ne peuvent donc pas être normalisés. Ces codes ne sont pas définis par le protocole WebSocket.
Codes commençant par 4
Code
Raison
Signification
4000–4999
Reserved for Private Use
Codes à usage privé. Ces codes sont assignés définitivement à des codes à usage privé et libre (non normalisés), mais non interopérables. Ces codes peuvent être utilisés comme code d'état dans une trame de contrôle de fermeture, à la suite d'un accord préalable entre les applications WebSocket.
Ce n'est pas précisé officiellement, mais une passerelle ou un proxy devrait transmettre sans modifications tout code à usage privé qu'elle ou il ne comprend pas, afin que l'accord puisse être directement établi entre le serveur final et le client final.
