1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
|
# SRT Rejection Codes
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](./docs/API/API-socket-options.md) document.
[:arrow_down: Jump to list of rejection codes](#api-function-rejection-codes)
## Summary 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](./docs/features/handshake.md) 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` = 0
- `SRT_REJC_PREDEFINED` = 1000
- `SRT_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.
### SRT Internal Rejection Codes
Defined in [**srt.h**](srtcore/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` = 0
- `SRT_REJ_SYSTEM` = 1
- ...
- `SRT_REJ_CRYPTO` = 17
See [the list below](#api-function-rejection-codes) for details.
### Extended Rejection Codes
As defined in [**access_control.h**](srtcore/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)
- ...
### User Defined Rejection Codes
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`).
## API Function Rejection Codes
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**](srtcore/srt.h) (click the *Rejection Reason* link to view a complete description).
| *Code* | *Rejection Reason* | *Since* | *Description* |
|:------:|:-------------------------------------------------- |:-------:|:-------------------------------------------------------------------------------------------------------------- |
| 0 | [SRT_REJ_UNKNOWN](#SRT_REJ_UNKNOWN) | 1.3.4 | Fallback value for cases where connection is not rejected. |
| 1 | [SRT_REJ_SYSTEM](#SRT_REJ_SYSTEM) | 1.3.4 | System function reported a failure. |
| 2 | [SRT_REJ_PEER](#SRT_REJ_PEER) | 1.3.4 | Connection rejected by peer, with no additional details. |
| 3 | [SRT_REJ_RESOURCE](#SRT_REJ_RESOURCE) | 1.3.4 | Problem with resource allocation (usually memory). |
| 4 | [SRT_REJ_ROGUE](#SRT_REJ_ROGUE) | 1.3.4 | Data sent by one party cannot be interpreted. |
| 5 | [SRT_REJ_BACKLOG](#SRT_REJ_BACKLOG) | 1.3.4 | Listener's backlog has been exceeded. |
| 6 | [SRT_REJ_IPE](#SRT_REJ_IPE) | 1.3.4 | Internal Program Error. |
| 7 | [SRT_REJ_CLOSE](#SRT_REJ_CLOSE) | 1.3.4 | Listener socket received a request as it is being closed. |
| 8 | [SRT_REJ_VERSION](#SRT_REJ_VERSION) | 1.3.4 | Minimum version requirement for a connection not satisfied by one party. |
| 9 | [SRT_REJ_RDVCOOKIE](#SRT_REJ_RDVCOOKIE) | 1.3.4 | Rendezvous cookie collision. |
| 10 | [SRT_REJ_BADSECRET](#SRT_REJ_BADSECRET) | 1.3.4 | Both parties have defined connection passphrases that differ. |
| 11 | [SRT_REJ_UNSECURE](#SRT_REJ_UNSECURE) | 1.3.4 | Only one party has set up a connection password. |
| 12 | [SRT_REJ_MESSAGEAPI](#SRT_REJ_MESSAGEAPI) | 1.3.4 | [`SRTO_MESSAGEAPI`](API-socket-options.md#SRTO_MESSAGEAPI) flag is different on both connection parties. |
| 13 | [SRT_REJ_CONGESTION](#SRT_REJ_CONGESTION) | 1.3.4 | Incompatible congestion-controller type. |
| 14 | [SRT_REJ_FILTER](#SRT_REJ_FILTER) | 1.3.4 | [`SRTO_PACKETFILTER`](API-socket-options.md#SRTO_PACKETFILTER) option is different on both connection parties. |
| 15 | [SRT_REJ_GROUP](#SRT_REJ_GROUP) | 1.4.2 | Group type or group settings are incompatible between connection parties. |
| 16 | [SRT_REJ_TIMEOUT](#SRT_REJ_TIMEOUT) | 1.4.2 | Connection not rejected, but timed out. |
| 17 | [SRT_REJ_CRYPTO](#SRT_REJ_CRYPTO) | 1.5.2 | Connection rejected due to unsupported or mismatching encryption mode. |
| | <img width=250px height=1px/> | | |
## Access Control Rejection Codes
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**](srtcore/access_control.h) (click the *Rejection Reason* link to view a complete description).
| *Code* | *Rejection Reason* | *Since* | *Description* |
|:------:|:------------------------------------------------- |:-------:|:-------------------------------------------------------------------------------------------------------------- |
| 1000 | [SRT_REJX_FALLBACK](#SRT_REJX_FALLBACK) | 1.4.2 | Callback handler has interrupted an incoming connection. |
| 1001 | [SRT_REJX_KEY_NOTSUP](#SRT_REJX_KEY_NOTSUP) | 1.4.2 | Key specified in StreamID string not supported by application. |
| 1002 | [SRT_REJX_FILEPATH](#SRT_REJX_FILEPATH) | 1.4.2 | Resource type designates file where path has wrong syntax or is not found. |
| 1003 | [SRT_REJX_HOSTNOTFOUND](#SRT_REJX_HOSTNOTFOUND) | 1.4.2 | The host specified in the `h` key cannot be identified. |
| 1400 | [SRT_REJX_BAD_REQUEST](#SRT_REJX_BAD_REQUEST) | 1.4.2 | General syntax error. |
| 1401 | [SRT_REJX_UNAUTHORIZED](#SRT_REJX_UNAUTHORIZED) | 1.4.2 | Authentication failed; client unauthorized to access the resource. |
| 1402 | [SRT_REJX_OVERLOAD](#SRT_REJX_OVERLOAD) | 1.4.2 | Server load too heavy to process request, or credit limit exceeded. |
| 1403 | [SRT_REJX_FORBIDDEN](#SRT_REJX_FORBIDDEN) | 1.4.2 | Access denied to the resource for any reason. |
| 1404 | [SRT_REJX_NOTFOUND](#SRT_REJX_NOTFOUND) | 1.4.2 | Resource specified by `r` and `h` keys cannot be found. |
| 1405 | [SRT_REJX_BAD_MODE](#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](#SRT_REJX_UNACCEPTABLE) | 1.4.2 | Unavailable parameters in `StreamID`, or `m=publish` data format not supported. |
| 1409 | [SRT_REJX_CONFLICT](#SRT_REJX_CONFLICT) | 1.4.2 | Resource specified by `r` and `h` keys is locked for modification. |
| 1415 | [SRT_REJX_NOTSUP_MEDIA](#SRT_REJX_NOTSUP_MEDIA) | 1.4.2 | Media type not supported by the application. |
| 1423 | [SRT_REJX_LOCKED](#SRT_REJX_LOCKED) | 1.4.2 | Resource is locked against any access. |
| 1424 | [SRT_REJX_FAILED_DEPEND](#SRT_REJX_FAILED_DEPEND) | 1.4.2 | Dependent entity for the request is not present. |
| 1500 | [SRT_REJX_ISE](#SRT_REJX_ISE) | 1.4.2 | Internal server error. |
| 1501 | [SRT_REJX_UNIMPLEMENTED](#SRT_REJX_UNIMPLEMENTED) | 1.4.2 | Request not supported by current version of the service. |
| 1502 | [SRT_REJX_GW](#SRT_REJX_GW) | 1.4.2 | Target endpoint rejected connection from gateway server |
| 1503 | [SRT_REJX_DOWN](#SRT_REJX_DOWN) | 1.4.2 | Service is down for maintenance. |
| 1505 | [SRT_REJX_VERSION](#SRT_REJX_VERSION) | 1.4.2 | SRT application version not supported. |
| 1507 | [SRT_REJX_NOROOM](#SRT_REJX_NOROOM) | 1.4.2 | Data stream cannot be archived due to lack of storage space. |
| | <img width=250px height=1px/> | | |
**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)?*
## API Function Rejection Reasons
#### SRT_REJ_UNKNOWN
A fallback value for cases when there was no connection rejected.
#### SRT_REJ_SYSTEM
One system function reported a failure. Usually this means some system
error or lack of system resources to complete the task.
#### SRT_REJ_PEER
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.
#### SRT_REJ_RESOURCE
A problem with resource allocation (usually memory).
#### SRT_REJ_ROGUE
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.
#### SRT_REJ_BACKLOG
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).
#### SRT_REJ_IPE
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).
#### SRT_REJ_CLOSE
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.
#### SRT_REJ_VERSION
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.
#### SRT_REJ_RDVCOOKIE
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.
#### SRT_REJ_BADSECRET
Both parties have defined a passphrase for a connection, but they differ.
#### SRT_REJ_UNSECURE
Only one connection party has set up a password. See also the
[`SRTO_ENFORCEDENCRYPTION`](API-socket-options.md#SRTO_ENFORCEDENCRYPTION) flag.
#### SRT_REJ_MESSAGEAPI
The value of the [`SRTO_MESSAGEAPI`](API-socket-options.md#SRTO_MESSAGEAPI)
flag is different on both parties in a connection.
#### SRT_REJ_CONGESTION
The [`SRTO_CONGESTION`](API-socket-options.md#SRTO_CONGESTION)option has
been set up differently on both parties in a connection.
#### SRT_REJ_FILTER
The [`SRTO_PACKETFILTER`](API-socket-options.md#SRTO_PACKETFILTER) option
has been set differently on both parties in a connection.
#### SRT_REJ_GROUP
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.
#### SRT_REJ_TIMEOUT
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`](API-socket-options.md#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.
#### SRT_REJ_CRYPTO
The connection was rejected due to a mismatch in crypto modes. See `SRTO_CRYPTOMODE`.
[:arrow_up: Back to top](#srt-rejection-codes)
## Access Control Rejection Reasons
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_PREDEFINED` and above: These are predefined errors. Errors from this
range (that is, below `SRT_REJC_USERDEFINED`) have their definitions provided in
the `access_control.h` public header file. The intention is that applications
using these codes understand the situations they describe in a standard way.
- `SRT_REJC_USERDEFINED` and 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`](docs/api/api-functions.md#srt-setrejectreason) function.
The SRT-specific codes are:
#### SRT_REJX_FALLBACK
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.
#### SRT_REJX_KEY_NOTSUP
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`.
#### SRT_REJX_FILEPATH
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.
#### SRT_REJX_HOSTNOTFOUND
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:
#### SRT_REJX_BAD_REQUEST
General syntax error. This can be reported in any case when parsing
the StreamID contents failed, or it cannot be properly interpreted.
#### SRT_REJX_UNAUTHORIZED
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.
#### SRT_REJX_OVERLOAD
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.
#### SRT_REJX_FORBIDDEN
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.
#### SRT_REJX_NOTFOUND
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.
#### SRT_REJX_BAD_MODE
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.
#### SRT_REJX_UNACCEPTABLE
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.
#### SRT_REJX_CONFLICT
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.
#### SRT_REJX_NOTSUP_MEDIA
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.
#### SRT_REJX_LOCKED
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.
#### SRT_REJX_FAILED_DEPEND
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.
#### SRT_REJX_ISE
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.
#### SRT_REJX_UNIMPLEMENTED
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).
#### SRT_REJX_GW
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.
#### SRT_REJX_DOWN
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.
#### SRT_REJX_VERSION
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.
#### SRT_REJX_NOROOM
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.
[:arrow_up: Back to top](#srt-rejection-codes)
|
