REQUEST_ERROR

10.6.1. Redirect Structure

A Redirect provides a way for an endpoint to direct the peer to retry a request at a different URI and/or for a different Full Track Name.

Redirect {
  Connect URI Length (vi64),
  Connect URI (..),
  Track Namespace (..),
  Track Name Length (vi64),
  Track Name (..),
}

• Connect URI: The URI to connect to for this track. If the length is zero, the requester SHOULD use the current session's URI. If a server receives a Redirect with a non-zero Connect URI Length it MUST close the session with a PROTOCOL_VIOLATION.

• Track Namespace and Track Name: The Track Namespace and Track Name to use for the redirected request. If both have zero length, the redirected request uses the same values as the original request. Otherwise, Track Namespace and Track Name are the literal values for the redirected request.

  Track Name is not meaningful for namespace-scoped requests (SUBSCRIBE_NAMESPACE, PUBLISH_NAMESPACE) and MUST be empty; an endpoint that receives a non-empty Track Name in a Redirect for a namespace-scoped request MUST close the session with a PROTOCOL_VIOLATION.

10.6.2. REQUEST_ERROR Message Format

REQUEST_ERROR Message {
  Type (vi64) = 0x5,
  Length (16),
  Error Code (vi64),
  Retry Interval (vi64),
  Error Reason (Reason Phrase),
  [Redirect (Redirect),]
}

• Error Code: Identifies an integer error code for request failure.

• Retry Interval: The minimum time (in milliseconds) before the request SHOULD be sent again, plus one. If the value is 0, the request SHOULD NOT be retried.

• Error Reason: Provides a text description of the request error. See Section 1.4.4.

• Redirect: Present only when Error Code is REDIRECT. See Section 10.6.1.

The application SHOULD use a relevant error code in REQUEST_ERROR, as defined below and assigned in Section 15.10.2. Most codepoints have identical meanings for various request types, but some have request-specific meanings.

If a request is retryable with the same parameters at a later time, the sender of REQUEST_ERROR includes a non-zero Retry Interval in the message. To minimize the risk of synchronized retry storms, the sender can apply randomization to each retry interval so that retries are spread out over time. A Retry Interval value of 1 indicates the request can be retried immediately.

INTERNAL_ERROR:

An implementation specific or generic error occurred.

UNAUTHORIZED:

The subscriber is not authorized to perform the requested action on the given track. This might be retryable if the authorization token is not yet valid.

TIMEOUT:

The subscription could not be completed before an implementation specific timeout. For example, a relay could not establish an upstream subscription within the timeout.

NOT_SUPPORTED:

The endpoint does not support the type of request.

MALFORMED_AUTH_TOKEN:

Invalid Auth Token serialization during registration (see Section 10.2.2).

EXPIRED_AUTH_TOKEN:

Authorization token has expired (Section 10.2.2).

GOING_AWAY:

The endpoint has received a GOAWAY and MAY reject new requests.

EXCESSIVE_LOAD:

The responder is overloaded and cannot process the request at this time. The sender SHOULD use the Retry Interval to indicate when the request can be retried.

UNSUPPORTED_EXTENSION:

The track contains a Mandatory Track Property (see Section 2.5.1) that the endpoint does not understand.

DUPLICATE_SUBSCRIPTION (0x19):

The PUBLISH or SUBSCRIBE request attempted to create a subscription to a Track with the same role as an existing subscription.

REDIRECT:

The request cannot be fulfilled by this endpoint, but could succeed at the location specified in the Redirect structure. The requester SHOULD establish a new session to the provided URI (if present) and retry the request using the Full Track Name from the Redirect (if present). This error code can appear in response to SUBSCRIBE, FETCH, TRACK_STATUS, PUBLISH_NAMESPACE and SUBSCRIBE_NAMESPACE. Relays are not required to follow redirects from upstream and MAY forward a REDIRECT response to matching downstream requests. A relay MAY cache a REDIRECT response for a Full Track Name for up to Retry Interval milliseconds and use it to respond to subsequent matching requests without forwarding them upstream.

Below are errors for use by the publisher. They can appear in response to SUBSCRIBE, FETCH, TRACK_STATUS, SUBSCRIBE_NAMESPACE, and SUBSCRIBE_TRACKS, unless otherwise noted.

DOES_NOT_EXIST:

The track or namespace is not available at the publisher.

INVALID_RANGE:

In response to SUBSCRIBE or FETCH, specified Filter or range of Locations cannot be satisfied.

MALFORMED_TRACK:

In response to a FETCH, a relay publisher detected the track was malformed (see Section 2.4.2).

The following are errors for use by the subscriber. They can appear in response to PUBLISH or PUBLISH_NAMESPACE, unless otherwise noted.

UNINTERESTED:

The subscriber is not interested in the track or namespace.

Errors below can only be used in response to one message type.

PREFIX_OVERLAP:

In response to SUBSCRIBE_NAMESPACE or SUBSCRIBE_TRACKS, the namespace prefix shares a common prefix with another subscription of the same type in the same session. SUBSCRIBE_NAMESPACE and SUBSCRIBE_TRACKS have independent overlap spaces, so a SUBSCRIBE_NAMESPACE and a SUBSCRIBE_TRACKS may share the same prefix.

NAMESPACE_TOO_LARGE:

In response to SUBSCRIBE_NAMESPACE or SUBSCRIBE_TRACKS, the namespace prefix matches more publishers than the relay is willing to enumerate.

INVALID_JOINING_REQUEST_ID:

In response to a Joining FETCH, the referenced Request ID is not an Established Subscription.