Solace REST Status Codes
The following section discusses the status codes and error response handing when sending REST messages to or when receiving REST messages from a PubSub+ event broker. It discusses expectations and requirements of the REST clients to ensure proper interworking with the event broker.
Solace HTTP Status Codes Overview
When responding to messages published to a PubSub+ event broker through Solace REST messaging, the event broker follows the Status Code Definitions as outlined in RFC 2616 and follows the guidelines outlined in the HTTP specification.
HTTP Responses from Event Broker to REST HTTP Clients
HTTP Status Codes in HTTP Responses from a Solace PubSub+ Event Broker to REST HTTP Clients
| Status Codes | PubSub+ Event Broker Behavior |
|---|---|
|
Successful 2xx |
A PubSub+ event broker responds with a 200 OK status code to indicate successful message processing. |
|
Redirection 3xx |
A PubSub+ event broker does not respond with any 3xx status codes. |
|
Client Error 4xx |
A PubSub+ event broker responds with a 4xx status code with a detailed response string for scenarios where the client seems to have erred. In general, it does not make sense to retry these requests without first correcting the error scenario. |
|
Server Error 5xx |
A PubSub+ event broker responds with a 5xx status code and a detailed response string for scenarios where the event broker encountered an error processing the request even though the request seems correct from a client perspective. This could be either a temporary or permanent condition. For example, the event broker could temporarily be out of resources to handle the request. In general, it may make sense to retry these requests because the condition may have cleared. |
|
Other status codes |
Solace reserves the right to introduce handling of new status codes as Solace REST messaging evolves. |
HTTP Responses from REST Consumers to Event Broker
HTTP Status Codes in HTTP Responses from REST Consumers to a Solace PubSub+ Event Broker
|
Status Codes |
PubSub+ Event Broker Behavior |
|---|---|
|
Successful 2xx |
A PubSub+ event broker treats 200, 201, 204, or 205 status codes as indicating successful message processing. It treats all other 2xx status codes as error scenarios and follows normal message error processing. |
|
Redirection 3xx |
A PubSub+ event broker does not expect 3xx status codes. Behavior is undefined if the REST consumer responds with 3xx status codes. |
|
Client Error 4xx |
A PubSub+ event broker treats 4xx status codes as error scenarios and follows normal message error processing. |
|
Server Error 5xx |
A PubSub+ event broker treats 5xx status codes as error scenarios and follows normal message error processing. |
|
Other status codes |
A Solace PubSub+ event broker does not expect status codes other than those listed above. The behavior is undefined if the REST consumer responds with other status codes. |
REST HTTP Client Requests to a Solace PubSub+ Event Broker
Success
A Solace PubSub+ event broker responds with a 200 OK status code when it successfully receives a REST message from a REST producer.
For persistent and non-persistent messages, this means that the event broker has successfully stored the ingress message in its message spool, and the event broker guarantees the delivery of this message. That is, 200 OK is returned only after the ingress message is successfully spooled.
For Direct messages, 200 OK is returned after the event broker successfully reads and parses the complete HTTP POST request from an authenticated connection. If the HTTP connection is unauthenticated, or if the connection's session parameters (authentication and/or client name) are changing, the event broker will not return any POST response until authentication processing is complete. The event broker responds with 200 OK prior to any further processing. So, for Direct messages, the client knows that the event broker accepted the message as correctly formatted and authenticated. If the event broker later discards this Direct message for other reasons, such as ACL denial on the message's topic, the client will not receive notification. The event broker tracks the discard reason in the event broker's statistics.
In request/reply scenarios, the event broker returns the 200 OK response only after the event broker receives the reply message. The contents of the reply are included in the body of the 200 OK response.
Failures
In general, for all failure cases where a Solace PubSub+ event broker needs to send a non-200 OK HTTP response back to a REST HTTP client, the response text is in the HTTP response header (possibly in summary form) and in the HTTP response body (possibly with additional detail). The tables below outline the expected error codes in more detail.
For a single HTTP POST request to Solace, two types of failures are possible:
- an authentication failure
- a messaging failure
Typically, authentication failures only occur on the first HTTP POST request over a new HTTP REST connection, or when the session parameters change on subsequent HTTP requests. Messaging failures can occur on any message.
A Solace PubSub+ event broker also returns error response details in the HTTP response body when failures occur. Refer to HTTP Response Body Format.
Authentication Failures
The table below provides a partial list of the failure codes a REST HTTP client can encounter when connecting to the event broker. The provided descriptions should be sufficient to correctly identify the root cause of the failure.
REST Producer Connectivity Failure Codes
|
Error Code |
Description |
|---|---|
|
403 Unauthorized |
The client authentication failed. |
|
403 Client Username Is Shutdown |
The username for the client is administratively shutdown on the event broker. |
|
403 Basic Authentication is Shutdown |
The client attempted to connect to an event broker that has basic authentication shutdown. |
|
403 Client Certificate Authentication is Shutdown |
The client attempted to connect to an event broker that has client certificate authentication shutdown. |
|
403 Client Name Already In Use |
The REST HTTP client is attempting to use a client name that is in use by another client on the event broker. Client names must be unique within a Message VPN. |
|
403 Forbidden |
The client login to the Message VPN on the event broker was denied because an ACL on the event broker for the given username/Message VPN has been configured to deny a client using the provided IP address/netmask. |
|
503 Message VPN Unavailable |
The Message VPN to which the REST HTTP client connects is currently shutdown on the event broker. |
Messaging Failures on HTTP POST Requests to Event Broker
REST Producer Publish Failure Codes lists some of the most common failure codes a REST HTTP client can encounter when sending requests to the event broker. It is not a full enumeration of all possible failure codes. In general, a REST HTTP client sending Guaranteed messages can receive all failure codes that a regular SMF client sending a message to a Solace PubSub+ event broker can receive.
For Direct messages from a REST producer, the response is returned after the event broker reads and parses the message from the HTTP connection, and performs any necessary authentication processing. So for Direct messages, it is possible for the event broker to later discard the message even though it responded with a 200 OK. This discard will be tracked by the event broker statistics and is similar in behavior to other event broker clients. The one exception to this is Direct message request/reply message exchange patterns, where the HTTP response is delayed until the reply is received by the event broker. Detailed error codes are returned to the REST producer in more scenarios.
The explanations in the failure code should be sufficient to correctly identify the root cause of the failure. In the table below, column “D” indicates the error code applies to Direct messages, and column “G” indicates the error code applies to Guaranteed messages (that is, persistent and non-persistent messages).
REST Producer Publish Failure Codes
|
Error Code |
Description |
D |
G |
|---|---|---|---|
|
400 Bad Request |
The HTTP request format was incorrect. Details of the reason are provided in the body of the message. |
Y |
Y |
|
400 Topic Parse Error |
The topic used unsupported syntax. |
Y |
Y |
|
400 Message Too Long |
The client attempted to send a message larger than the event broker supports. |
Y |
Y |
|
400 Queue Not Found |
The REST producer attempted to POST to an unknown queue. |
N |
Y |
|
403 Publish ACL Denied |
A message from a REST producer could not be published because its topic matched that of a topic defined as disallowed in an ACL on the event broker for the given username and Message VPN. |
N |
Y |
|
405 Method Not Allowed |
The event broker only accepts POST request methods. Other HTTP request methods are unsupported and generate this error. |
Y |
Y |
|
408 Request Timeout |
The event broker timed out when attempting to read the HTTP POST request from the REST HTTP client. |
Y |
Y |
|
500 Internal Server Error |
There were other reasons the HTTP POST request could not be processed. The issue should be reported to Solace support for investigation. |
N |
Y |
|
503 Spool Over Quota |
The message was not delivered because the Guaranteed Message spool is over its allotted space quota. |
N |
Y |
|
503 Queue Shutdown |
An attempt was made to operate on a shutdown queue. |
N |
Y |
|
503 Service Unavailable |
Guaranteed Messaging service is not enabled on the event broker. |
N |
Y |
|
504 Gateway Timeout |
The event broker timed out while waiting for an expected reply message. |
Y |
Y |
HTTP Response Body Format
In addition to the information provided in the HTTP response header described above, when a Solace PubSub+ event broker does not successfully receive a REST message from the REST HTTP client, the event broker provides error response details in the HTTP response body. The root element is the <solace-error-response> element. This element can have up to three children.
REST Response Body XML Details
|
XML Element |
Description |
|---|---|
|
code |
The HTTP status code for the failure. |
|
reason |
The HTTP status message for the failure. |
|
detail |
A text description of the failure providing additional details related to the problem in human‑readable text. |
|
Internal-use |
The value is a Solace PubSub+ version specific ID to aid with internal Solace debugging. |
The following is an example of a Solace error response body:
<solace-error-response>
<code>403</code>
<reason><![CDATA[Publish ACL Denied]]></reason>
<detail><![CDATA[
Topic "/QUEUE/acl/topic";
SMF AD control client ack response error
]]></detail>
<internal-use>2:10960</internal-use>
</solace-error-response>
HTTP Connection Termination by Event Broker
A Solace PubSub+ event broker terminates the HTTP connection of a REST HTTP client for the following reasons:
- HTTP header parse errors—The received HTTP header is not in a valid format and cannot be parsed. Therefore, there is no way to proceed with the REST session. REST clients must send properly formatted HTTP when communicating with the event broker.
- Timeout waiting for authentication—If a REST client opens a HTTP connection to a Solace PubSub+ event broker, the event broker will not wait indefinitely to authenticate a client. After a period of time the event broker closes the REST HTTP client connection.
- Timeout waiting for a complete message—A Solace PubSub+ event broker will not wait indefinitely for HTTP request completion when reading from the HTTP client’s connection. After a period of time the event broker closes the REST HTTP client session if the event broker has received only a partial request.
- Various shutdowns (including username, Message VPN, service, and so on) within Solace event broker management, administrative disconnections, or activity switches. These take effect immediately, even if the event broker has not finished sending an HTTP POST response.
- Slow client—If the event broker as a whole is running low on resources, any client that is consuming a large number of those resources but is unable to keep up with the traffic load it is offered may have its connection disconnected. For example, if a REST HTTP producer sends a synchronous request/reply message, and the reply message has a large payload, but the REST HTTP producer is slow at draining that payload (either because the client cannot take it or there is a network impairment towards the client), then the REST HTTP producer’s connection may become eligible for disconnection as a slow client.
Event Broker HTTP Requests to REST Consumers
Indicating Success to Event Broker
REST consumers must respond with a status of 200, 201, 204, or 205 to indicate successful message processing. The contents of any reply are included in the body of the HTTP response.
Indicating Failures to Event Broker
REST consumers can use 4xx or 5xx response codes to provide more detail for why a message is being rejected. REST consumers must restrict HTTP response codes used for errors because Solace PubSub+ event broker behavior is undefined for error response codes other than 4xx and 5xx.
A Solace PubSub+ event broker keeps the most recent response codes for rejected messages similar to how no-subscription-match discards are logged. The log can be a useful location for debugging information related to REST consumer delivery failures.
Additionally, for non-persistent and persistent messages, the event broker will retry delivery based on the settings on the event broker for any 4xx and 5xx response codes. Each delivery failure will be captured in the log. The Max Retry setting on the corresponding Solace queue controls the number of delivery retries that the event broker will attempt.
The default Max Retry setting on an event broker queue is infinite (that is, message delivery will be retried forever). Therefore, it is recommended that Solace PubSub+ event broker administrators specify an appropriate value for their application to avoid messages being redelivered indefinitely to clients that are unable to handle them.
If a message exhausts the retries, then it will follow regular Solace Guaranteed message handling and statistics are available that show what happened to the message which will be one of either discarded or moved to the DMQ depending on message flags.