This document provides an overview of the rejection (error) codes used by and supported within SRT and SRT-based applications. For information on other types of error codes refer to the API Socket Options document.
⬇️ Jump to list of rejection codes
Rejection codes are used in the SRT API, and are transferred on the wire as a part of a Handshake packet (refer to the Handshake Type field of the Handshake packet).
The rejection codes are divided into several ranges:
- SRT internal
- Predefined application level codes
- User defined (custom) codes
In the SRT API these ranges are marked with the following constants (preprocessor definitions):
SRT_REJC_INTERNAL= 0SRT_REJC_PREDEFINED= 1000SRT_REJC_USERDEFINED= 2000
When transferred on the wire, the API value is incremented by 1000 to become the Handshake Type field value. In the following sections the values of rejection reason codes are given in accordance with the API values.
Defined in srt.h, these codes provide the reason why a connection is rejected by SRT. They cover the reserved range 0 - 999 (below SRT_REJC_PREDEFINED). These codes cannot be used by applications to report a rejection reason.
Naming: SRT_REJ_*
SRT_REJ_UNKNOWN= 0SRT_REJ_SYSTEM= 1- ...
SRT_REJ_CRYPTO= 17 See the list below for details.
As defined in access_control.h, these are standard server error codes including those adopted from HTTP. They provide the reason why an application rejects a connection. The value is expected to be set by an application via the listener callback if it wants to reject an incoming connection request. These codes cover the reserved range 1000 - 1999 (SRT_REJC_PREDEFINED - SRT_REJC_USERDEFINED).
Subranges (1000 + value):
- 0 - 99: Reserved for unique SRT-specific codes (unused by HTTP)
- 100 - 399: Info, Success, and Redirection in HTTP (unused by SRT)
- 400 - 599: Client and server errors in HTTP (adopted by SRT)
Naming: SRT_REJX_*
Example:
SRT_REJX_KEY_NOTSUP(1001): The key used in the StreamID keyed string is not supported by the service.SRT_REJX_BAD_REQUEST(1400)- ...
These codes can be freely defined by an application. They can be custom codes, not adopted by other vendors. For example, 2005: “Makito license expired”. They cover the reserved range 2000 - 2999 (higher than SRT_REJC_USERDEFINED).
SRT's API function rejection codes refer to system-level error conditions caused by SRT-specific settings or operating conditions. They are uninfluenced by application-related events, and applications are not permitted to use or simulate these codes.
The table below lists the rejection codes as defined in srt.h (click the Rejection Reason link to view a complete description).
| Code | Rejection Reason | Since | Description |
|---|---|---|---|
| 0 | SRT_REJ_UNKNOWN | 1.3.4 | Fallback value for cases where connection is not rejected. |
| 1 | SRT_REJ_SYSTEM | 1.3.4 | System function reported a failure. |
| 2 | SRT_REJ_PEER | 1.3.4 | Connection rejected by peer, with no additional details. |
| 3 | SRT_REJ_RESOURCE | 1.3.4 | Problem with resource allocation (usually memory). |
| 4 | SRT_REJ_ROGUE | 1.3.4 | Data sent by one party cannot be interpreted. |
| 5 | SRT_REJ_BACKLOG | 1.3.4 | Listener's backlog has been exceeded. |
| 6 | SRT_REJ_IPE | 1.3.4 | Internal Program Error. |
| 7 | SRT_REJ_CLOSE | 1.3.4 | Listener socket received a request as it is being closed. |
| 8 | SRT_REJ_VERSION | 1.3.4 | Minimum version requirement for a connection not satisfied by one party. |
| 9 | SRT_REJ_RDVCOOKIE | 1.3.4 | Rendezvous cookie collision. |
| 10 | SRT_REJ_BADSECRET | 1.3.4 | Both parties have defined connection passphrases that differ. |
| 11 | SRT_REJ_UNSECURE | 1.3.4 | Only one party has set up a connection password. |
| 12 | SRT_REJ_MESSAGEAPI | 1.3.4 | SRTO_MESSAGEAPI flag is different on both connection parties. |
| 13 | SRT_REJ_CONGESTION | 1.3.4 | Incompatible congestion-controller type. |
| 14 | SRT_REJ_FILTER | 1.3.4 | SRTO_PACKETFILTER option is different on both connection parties. |
| 15 | SRT_REJ_GROUP | 1.4.2 | Group type or group settings are incompatible between connection parties. |
| 16 | SRT_REJ_TIMEOUT | 1.4.2 | Connection not rejected, but timed out. |
| 17 | SRT_REJ_CRYPTO | 1.5.2 | Connection rejected due to unsupported or mismatching encryption mode. |
SRT's access control rejection codes are intended for use by applications to forcefully reject connections in SRT listener callbacks. They are intended only as a guide to promote standardization. If they are used in an application, a description of their specific implementation should be published (the descriptions in this documentation are not definitive).
The table below lists the rejection codes as defined in access_control.h (click the Rejection Reason link to view a complete description).
| Code | Rejection Reason | Since | Description |
|---|---|---|---|
| 1000 | SRT_REJX_FALLBACK | 1.4.2 | Callback handler has interrupted an incoming connection. |
| 1001 | SRT_REJX_KEY_NOTSUP | 1.4.2 | Key specified in StreamID string not supported by application. |
| 1002 | SRT_REJX_FILEPATH | 1.4.2 | Resource type designates file where path has wrong syntax or is not found. |
| 1003 | SRT_REJX_HOSTNOTFOUND | 1.4.2 | The host specified in the h key cannot be identified. |
| 1400 | SRT_REJX_BAD_REQUEST | 1.4.2 | General syntax error. |
| 1401 | SRT_REJX_UNAUTHORIZED | 1.4.2 | Authentication failed; client unauthorized to access the resource. |
| 1402 | SRT_REJX_OVERLOAD | 1.4.2 | Server load too heavy to process request, or credit limit exceeded. |
| 1403 | SRT_REJX_FORBIDDEN | 1.4.2 | Access denied to the resource for any reason. |
| 1404 | SRT_REJX_NOTFOUND | 1.4.2 | Resource specified by r and h keys cannot be found. |
| 1405 | SRT_REJX_BAD_MODE | 1.4.2 | Mode specified in the m key in StreamID is not supported for this request. |
| 1406 | SRT_REJX_UNACCEPTABLE | 1.4.2 | Unavailable parameters in StreamID, or m=publish data format not supported. |
| 1409 | SRT_REJX_CONFLICT | 1.4.2 | Resource specified by r and h keys is locked for modification. |
| 1415 | SRT_REJX_NOTSUP_MEDIA | 1.4.2 | Media type not supported by the application. |
| 1423 | SRT_REJX_LOCKED | 1.4.2 | Resource is locked against any access. |
| 1424 | SRT_REJX_FAILED_DEPEND | 1.4.2 | Dependent entity for the request is not present. |
| 1500 | SRT_REJX_ISE | 1.4.2 | Internal server error. |
| 1501 | SRT_REJX_UNIMPLEMENTED | 1.4.2 | Request not supported by current version of the service. |
| 1502 | SRT_REJX_GW | 1.4.2 | Target endpoint rejected connection from gateway server |
| 1503 | SRT_REJX_DOWN | 1.4.2 | Service is down for maintenance. |
| 1505 | SRT_REJX_VERSION | 1.4.2 | SRT application version not supported. |
| 1507 | SRT_REJX_NOROOM | 1.4.2 | Data stream cannot be archived due to lack of storage space. |
NOTE: SRT rejection codes follow this prefix convention:
SRT_REJ: standard rejection codes from SRT API functions (0 - 99)SRT_REJC: mark the border values between ranges.SRT_REJX: extended rejection codes (code values above 1000).above)?*
A fallback value for cases when there was no connection rejected.
One system function reported a failure. Usually this means some system error or lack of system resources to complete the task.
The connection has been rejected by the peer, but no further details are available. This usually means that the peer doesn't support rejection reason reporting.
A problem with resource allocation (usually memory).
The data sent by one party to another cannot be properly interpreted. This should not happen during normal usage, unless it's a bug, or some weird events are happening on the network.
The listener's backlog has exceeded its queue limit (there are many other callers waiting for the opportunity to be connected and the "wait queue" has reached its limit).
Internal Program Error. This should not happen during normal usage. It usually indicates a bug in the software (although this can be reported by both local and foreign hosts).
The listener socket was able to receive the request, but is currently being closed. It's likely that the next request will result in a timeout.
One party in the connection has set up a minimum version that is required for that connection, but the other party doesn't satisfy this requirement.
Rendezvous cookie collision. Normally, the probability that this will happen is negligible. However, it can result from a misconfiguration when, in attempting to make a rendezvous connection, both parties try to bind to the same IP address, or both are local addresses of the same host. In such a case the sent handshake packets are returned to the same host as if they were sent by the peer (i.e. a party is sending to itself). In such situations, this reject reason will be reported for every attempt.
Both parties have defined a passphrase for a connection, but they differ.
Only one connection party has set up a password. See also the
SRTO_ENFORCEDENCRYPTION flag.
The value of the SRTO_MESSAGEAPI
flag is different on both parties in a connection.
The SRTO_CONGESTIONoption has
been set up differently on both parties in a connection.
The SRTO_PACKETFILTER option
has been set differently on both parties in a connection.
The group type or some group settings are incompatible between connection parties. While every connection within a bonding group may have different target addresses, they should all designate the same endpoint and the same SRT application. If this condition isn't satisfied, then the peer will respond with a different peer group ID for the connection that is trying to contact a machine/application that is completely different from the existing connections in the bonding group.
The connection wasn't rejected, but it timed out. This code is always sent on
a connection timeout, but this is the only way to get this state in non-blocking
mode (see SRTO_RCVSYN).
There may also be server and user rejection codes, as defined by the
SRT_REJC_INTERNAL, SRT_REJC_PREDEFINED, and SRT_REJC_USERDEFINED
constants. Note that the number space from the value of SRT_REJC_PREDEFINED
and above is reserved for "predefined codes" (SRT_REJC_PREDEFINED value plus
adopted HTTP codes). Values above SRT_REJC_USERDEFINED are freely defined by
the application.
The connection was rejected due to a mismatch in crypto modes. See SRTO_CRYPTOMODE.
An SRT listener callback handler can decide to reject an incoming connection.
Under normal circumstances, the rejection code is predefined as SRT_REJ_RESOURCE.
The handler can, however, set its own rejection code. There are two numbered spaces
intended for this purpose (as the range below SRT_REJC_PREDEFINED is reserved
for internal codes):
-
SRT_REJC_PREDEFINEDand above: These are predefined errors. Errors from this range (that is, belowSRT_REJC_USERDEFINED) have their definitions provided in theaccess_control.hpublic header file. The intention is that applications using these codes understand the situations they describe in a standard way. -
SRT_REJC_USERDEFINEDand above: These are errors that are freely defined by the application. Codes from this range can be only understood if each application knows the code definitions of the other. These codes should be used only after making sure that the applications at either end of a connection understand them.
The intention here is for the predefined codes to be consistent with the HTTP
standard codes. Such code can be set by using the srt_setrejectreason function.
The SRT-specific codes are:
This code should be set by the callback handler in the beginning in case the application needs to be informed that the callback handler actually has interpreted the incoming connection, but hasn't set a more appropriate code describing the situation.
Indicates there was a key specified in the StreamID string that this application
doesn't support. Note that it's not obligatory for the application to
react this way - it may chose to ignore unknown keys completely, or
to have some keys in the ignore list (which it won't interpret, but tolerate)
while rejecting any others. It is also up to the application
to decide to return this specific error, or more generally report
the syntax error with SRT_REJX_BAD_REQUEST.
The resource type designates a file, and the path either has the wrong syntax
or is not found. In the case where t=file, the path should be specified under
the r key, and the file specified there must be able to be saved this way.
It's up to the application to decide how to treat this path, how to parse it,
and what this path specifically means. For the r key, the application should
at least handle the single filename, and have storage space available to save
it (provided a file of the same name does not already exist there). The
application should decide whether and how to handle all other situations (like
directory path, special markers in the path to be interpreted by the
application, etc.), or to report this error.
The host specified in the h key cannot be identified. The h key is
generally for a situation when you have multiple DNS names for a host,
so an application may want to extract the name from the URI and set it
to the h key so that the application can distinguish the request also by
the target host name. The application may, however, limit the number of
recognized services by host name to some predefined names and not
handle the others, even if this is properly resolved by DNS. In this
case it should report this error.
The other error codes are HTTP codes adapted for SRT:
General syntax error. This can be reported in any case when parsing the StreamID contents failed, or it cannot be properly interpreted.
Authentication failed, which makes the client unauthorized to access the
resource. This error, however, confirms that the syntax is correct and
the resource has been properly identified. Note that this cannot be
reported when you use a simple user-password authentication
method because in this case the password is verified only after the
listener callback handler accepts the connection. This error is rather
intended to be reported in the case of t=auth when the authentication
process has generated some valid session ID, but then the session
connection has specified a resource that is not within the frames
of that authentication.
The server is too heavily loaded to process the request, or the credit limit for accessing the service and the resource has been exceeded. In HTTP the description mentions payment for a service, but it is also used by some services for general "credit" management for a client. In SRT it should be used when the service is doing any kind of credit management to limit access to selected clients that "have" enough credit, even if the credit is something the client can recharge itself, or that can be granted depending on available service resources.
Access denied to the resource for any reason. This error is
independent of an authorization or authentication error (as reported
by SRT_REJX_UNAUTHORIZED). The application can decide which
is more appropriate. This error is usually intended for
a resource that should only be accessed after a successful
authorization over a separate auth-only connection, where the query
in StreamID has correctly specified the resource identity and mode,
but the session ID (in the s key) is either (a) not specified, or
(b) specifies a valid session, but the authorization region for this
session does not include the specified resource.
The resource specified in the r key (in combination with the h key)
is not found at this time. This error should be only reported if the
information about resource accessibility is allowed to be publicly
visible. Otherwise, the application might report authorization
errors.
The mode specified in the m key in StreamID is not supported for this request.
This may apply to read-only or write-only resources, as well when interactive
(bidirectional) access is not valid for a resource.
Applies when the parameters specified in StreamID cannot be satisfied for the
requested resource, or when m=publish but the data format is not acceptable.
This is a general error reporting an unsupported format for data that appears to
be wrong when sending, or a restriction on the data format (as specified in the
details of the resource specification) such that it cannot be provided
when receiving.
The resource being accessed (as specified by r and h keys) is locked for
modification. This error should only be reported for m=publish when the
resource being accessed is read-only because another client (not necessarily
connected through SRT):
- is currently publishing into this resource
- has reserved this resource ID for publishing
Note that this error should be reported when there is no other reason for having a problem accessing the resource.
The media type is not supported by the application. The media type is
specified in the t key. The currently standard types are
stream, file and auth. An application may extend this list, and
is not obliged to support all of the standard types.
The resource being accessed is locked against any access. This is similar to
SRT_REJX_CONFLICT, but in this case the resource is locked for reading
and writing. This is for when the resource should be shown as existing and
available to the client, but access is temporarily blocked.
The dependent entity for the request is not present. In this case the
dependent entity is the session, which should be specified in the s
key. This means that the specified session ID is nonexistent, or it
has already expired.
Internal server error. This is for a general case when a request has been correctly verified, with no related problems found, but an unexpected error occurs after the processing of the request has started.
The request was correctly recognized, but the current software version
of the service (be it SRT or any other software component) doesn't
support it. This should be reported for a case where some features to
be specified in the StreamID request are supposed to be supported in a
predictable future, but the current version of the server does not
support it, or the support for this feature in this version has been
temporarily blocked. This shouldn't be reported for existing features that are
being deprecated, or older features that are no longer supported
(for this case the general SRT_REJX_BAD_REQUEST is more appropriate).
The server acts as a gateway and the target endpoint rejected the connection. The reason the connection was rejected is unspecified. The gateway cannot forward the original rejection code from the target endpoint because this would suggest the error was on the gateway itself. Use this error with some other mechanism to report the original target error, if possible.
The service is down for maintenance. This can only be reported when the service has been temporarily replaced by a stub that is only reporting this error, while the real service is down for maintenance.
Application version not supported. This can refer to an application feature that is unsupported (possibly from an older SRT version), or to a feature that is no longer supported because of backward compatibility requirements.
The data stream cannot be archived due to a lack of storage space. This is reported when a request to send a file or a live stream to be archived is unsuccessful. Note that the length of a file transmission is usually pre-declared, so this error can be reported early. It can also be reported when the stream is of undefined length, and there is no more storage space available.