Error Messages (Protocol)

Error messages indicate a failure in parsing, authentication, execution, or security. Parsing failures may indicate malformed messages or garbage tokens. Authentication failures may indicate incorrect entity or user credentials. Execution failures may indicate network or backend service problems. Security failures may indicate incorrect message characteristics for the required message security.

Responding

The entity must respond with a MSL error message if an error occurs within the MSL stack. Applications may not directly choose to respond with MSL error messages. The error code indicates the action (if any) that the requesting entity may take to successfully retry the request.

The MSL error message should specify the message recipient if possible.

Receiving

Any error parsing, processing, or authenticating a received error message should be treated as receipt of an error message containing the error code 1 Fail.

The MSL stack may choose to accept an error message with a message ID not equal to the request message ID + 1 if the error code is 1 Fail, 2 Transient Failure, 3 Entity Re-authenticate, or 6 Entity Data Re-authenticate as those error codes indicate a potential problem with the local entity’s master token or entity authentication data which could prevent the remote entity from extracting the request message ID. Accepting such error messages allows such error messages to be replayed but also allows the local entity to correct the problem in the case of 3 Entity Re-authenticate or 6 Entity Data Re-authenticate.

Each error code must be handled as follows. Note that when requesting data from the application, it is often useful to inform the application of the error code that triggered the request. This allows the application to provide the correct data or abort the operation.

Error Code	Action	Behavior
1	Fail	1. Return the error message to the application.
2	Transient Failure	1. Return the error message to the application.
3	Entity Re-authenticate	1. Request entity authentication data from the application. 2. Resend the request with entity authentication data and without a master token or user ID token.
4	User Re-authenticate	1. Request user authentication data from the application. 2. If encryption is possible, resend the request with user authentication data and without a user ID token. 3. Else perform a MSL handshake and upon success resend the request with user authentication data and without a user ID token.
5	Key Exchange Required	1. Resend the request with the renewable flag true and key request data.
6	Entity Data Re-authenticate	1. Request new entity authentication data from the application. 2. If new entity authentication data is unavailable then return the error message to the application. 3. Else continue as indicated under 3 Entity Re-authenticate.
7	User Data Re-authenticate	1. Request new user authentication data from the application. 2. If new data is unavailable then return the error message to the application. 3. Else continue as indicated under 4 User Re-authenticate.
8	Expired	1. If there is a new master token, resend the request using it. 2. Else resend the request with the renewable flag true and key request data.
9	Replayed	1. Resend the request with a larger non-replayable ID.
10	SSO Token Rejected	1. Request new user authentication data from the application. 2. If new data is unavailable then return the error message to the application. 3. Else continue as indicated under 4 User Re-authenticate.

Messages sent by the MSL stack in response to an error message must:

• Use a message ID one larger than the error message’s message ID.
• Honor the original request’s non-replayable and encrypted properties if application data is included.