Ably's client library SDKs, and the core realtime platform, use common error codes. These error codes are stored and maintained in the shared public JSON file errors.json.
In addition, a list of error codes and corresponding support articles to help understand how to resolve common problems relating to these error codes can be seen in errorsHelp.json.
This ensures that with every Ably error message that includes a help link for the error in the format https://help.ably.io/error/{{ERROR_CODE}}, the user is taken to a relevant FAQ if it exists, and if one does not exist, we record the number of times that error code has been visited so that the docs/support team can work on adding relevant documentation.
See the ably/help repository (internal), the "simple help redirect site".
If you need help understanding any error codes, or need technical support, please visit the Ably support desk.
Codes in errors.json fall into these ranges:
| From | Title |
|---|---|
| 10000 | Generic |
| 40000 | 400 |
| 40100 | 401 |
| 40300 | 403 |
| 40400 | 404 |
| 40500 | 405 |
| 40900 | 409 |
| 41001 | 410 |
| 42200 | 422 |
| 42910 | 429 |
| 50000 | 500 |
| 50010 | Edge cacheing / proxy service |
| 50320 | Active Traffic Management error code to indicate intentional redirect of traffic to fallback hosts |
| 50330 | DNS switch over |
| 50410 | Edge cacheing / proxy service |
| 60000 | reserved for internal (non-customer-facing) use |
| 70000 | reactor-related |
| 71000 | exchange-related: general |
| 71100 | exchange-related: publisher |
| 71200 | exchange-related: product |
| 71300 | exchange-related: subscription |
| 80000 | connection-related |
| 90000 | channel-related |
Codes above 100000 are reserved for use by specific Ably projects and ecosystems, where these codes are unknown to the core Ably service. Definitions for these ranges are defined below.
Codes for Asset Tracking are maintained externally.
| From | To | Location of Definitions |
|---|---|---|
| 100000 | 100999 | Specification: Error codes |
| From | Title |
|---|---|
| 101000 | Space name missing |
| 101001 | Not entered space |
| 101002 | Lock request exists |
| 101003 | Lock is locked |
| 101004 | Lock invalidated |
102000 - 102999 are reserved for chat purposes.
A list of agents announced by Ably client libraries can be found in agents.json.
See RSC7d for more information on the Agent library identifier and the Ably-Agent HTTP header.
When a new agent is added to a client library, add a corresponding entry to agents.json
using the schema defined in agents-schema.json, and open a pull
request against the main branch with those changes.
Once the pull request is merged into main, open an internal ticket requesting that the realtime team
follow the "Publishing Changes" steps below.
The following table adds more contextual detail for some agent identifiers, where:
- The table does not include those where
typeissdk. In these cases there is always only a single emitter, where the identifier value matches the name of the SDK source code repository in theablyGitHub org - e.g. identifierably-jsis emitted by ably-js. - The table rows are sorted alphabetically by identifier.
- It intentionally does not include columns that repeat information that is already canonically defined in agents.json (e.g. values of
versionedandtype). - The 'Emitters' column provides links to SDK source code repositories which directly emit this identifier.
| Identifier | Emitters |
|---|---|
ably-asset-tracking-android |
ably-asset-tracking-android |
ably-asset-tracking-swift |
ably-asset-tracking-swift |
ably-flutter |
ably-flutter |
ably-ruby-rest |
ably-ruby |
android |
ably-java, ably-dotnet |
browser |
ably-js |
chat-js |
ably-chat-js |
chat-react |
ably-chat-js |
dart |
ably-flutter |
darwin |
ably-go |
dotnet-framework |
ably-dotnet |
dotnet-standard |
ably-dotnet |
go |
ably-go |
iOS |
ably-cocoa, ably-dotnet |
jre |
ably-java |
kafka-connect-ably |
kafka-connect-ably |
laravel |
ably-php |
laravel-broadcaster |
ably-php |
laravel-echo |
ably-js |
linux |
ably-dotnet, ably-go |
macOS |
ably-cocoa, ably-dotnet |
nativescript |
ably-js |
nodejs |
ably-js |
php |
ably-php |
python |
ably-python |
react-hooks |
react-hooks |
react-native |
ably-js |
ruby |
ably-ruby |
spaces |
spaces |
models |
models |
tvOS |
ably-cocoa |
unity |
ably-dotnet |
uwp |
ably-dotnet |
watchOS |
ably-cocoa |
windows |
ably-dotnet, ably-go |
xamarin |
ably-dotnet |
After changes to agents.json have been merged into main, update the generated Go code
in the ably-common-go repository by manually triggering the
publish workflow (see here
for instructions on how to do that).
There is no further, immediate downstream impact of publishing to ably-common-go like this.
Therefore it is safe to publish without consulting others because they have an explicit step required to update the submodule in their codebase (see Step 2: Internal).
Once the generated Go code has been updated, update the ably-common-go module in the
internal go-services repository by running:
go get -u github.com/ably/ably-common-goOpen a pull request with the resulting changes to go.mod and go.sum, and once merged deploy the router
so that it's aware of the newly added agent identifiers.
The ablyLibMappings field in agents.json provides continuity for SDKs that continue to send the
deprecated X-Ably-Lib header, which was not capable of sending the extra information we now send in the Ably-Agent
header. Each entry in ablyLibMappings is used server-side to map an old X-Ably-Lib value to its equivalent new
Ably-Agent value.
For example, an old client that sends the header X-Ably-Lib: js-web-1.1.0 will be mapped to Ably-Agent: ably-js/1.1.0 browser
based on the js-web entry, and then handled as if it sent that Ably-Agent header directly.
It is not expected that any new mappings will be added, since we shouldn't be sending any new types of values using the deprecated
X-Ably-Lib header, any newly released code should be sending the Ably-Agent header instead.