Skip to content

protocol

Directory actions

More options

Directory actions

More options

Latest commit

 

History

History

protocol

Folders and files

NameName
Last commit message
Last commit date

parent directory

..
.ruby-version
.ruby-version
 
 
Gemfile
Gemfile
 
 
Gemfile.lock
Gemfile.lock
 
 
README.md
README.md
 
 
Rakefile
Rakefile
 
 
agents.json
agents.json
 
 
errors.json
errors.json
 
 
errorsHelp.json
errorsHelp.json
 
 

README.md

Ably Realtime Protocol

Error Codes

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.

Ranges

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.

Asset Tracking

Codes for Asset Tracking are maintained externally.

From To Location of Definitions
100000 100999 Specification: Error codes

Spaces

From Title
101000 Space name missing
101001 Not entered space
101002 Lock request exists
101003 Lock is locked
101004 Lock invalidated

Chat

102000 - 102999 are reserved for chat purposes.

Agents

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.

Agent CSV Data

Agent metadata and release information is automatically exported to CSV files and published to S3 for analytics and reporting purposes. These files are publicly accessible at:

The CSV files are automatically regenerated and uploaded:

  • Daily at 2 AM UTC (via scheduled workflow)
  • When changes are made to protocol/agents.json or the export scripts
  • Manually via the Sync Data to S3 workflow

Generating CSV Files Locally

To generate the CSV files locally for testing:

# Generate agent metadata CSV
npm run export:agents

# Generate release data (requires GITHUB_TOKEN and OPENAI_API_KEY in .env)
npm run fetch:agent-releases

The generated files will be created in the data/agents/ directory (which is git-ignored).

Testing S3 Upload Locally

To test the upload configuration without actually uploading to S3:

# Dry-run mode (no AWS credentials required)
npm run upload:s3 -- --dry-run

Note: Actual uploads to S3 require AWS credentials. The production schemas.ably.com bucket uses the ably-sdk-schemas-ably-common IAM role, which is only available in GitHub Actions. Local users typically won't have direct access to upload to the production bucket.

AWS Credentials for Local Upload

If you need to upload to S3 locally (e.g., to a test bucket), you must have AWS CLI installed and configured:

# Install AWS CLI if not already installed
brew install awscli  # macOS
# or
apt-get install awscli  # Ubuntu/Debian

# Configure AWS credentials (creates a 'default' profile)
aws configure

You can also specify a different AWS profile by setting the AWS_PROFILE environment variable in your .env file:

AWS_PROFILE=your-profile-name

For uploading to a different bucket (for testing), set these in your .env:

S3_BUCKET=your-test-bucket
S3_PREFIX=csv/agents
AWS_PROFILE=your-profile-name

Adding New Agents

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.

Analytics pipeline support

The agents are replicated in the analytics pipeline that processes agent headers. See udtf_parse_ably_agent.py.

Once the pull request is merged into main, notify the Data / Infrastructure team of the changes to agents.json so that they can update the analytics data pipeine to support the newly added agents.

Additional Notes on Agents

The following table adds more contextual detail for some agent identifiers, where:

  • The table does not include those where type is sdk. In these cases there is always only a single emitter, where the identifier value matches the name of the SDK source code repository in the ably GitHub org - e.g. identifier ably-js is 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 versioned and type).
  • 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-cli ably-cli command line CLI too
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
chat-kotlin ably-chat-kotlin
chat-swift ably-chat-swift
chat-react-ui-components ably-chat-react-ui-components (Deprecated, use chat-react-ui-kit
chat-react-ui-kit ably-chat-react-ui-kit
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

ablyLibMappings

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.

Guidance adding custom agents to SDKs and/or Control API

Adding Custom Agent Headers

When implementing Ably functionality in tools, wrappers, or integrations, it's important to add custom agent headers to help track usage and debug issues. Here's how to add agent headers in different contexts:

1. Using Ably SDK (JavaScript/TypeScript)

For REST or Realtime clients, use the agents property in ClientOptions:

const client = new Ably.Realtime({
  key: 'your-api-key',
  agents: {
    'your-agent-name': 'version'  // e.g., 'ably-cli': '0.7.7'
  }
});
  1. Direct HTTP Requests

When making direct HTTP requests to Ably APIs, add the Ably-Agent header:

fetch('https://api.ably.com/endpoint', {
  headers: {
    'Authorization': 'Bearer your-token',
    'Ably-Agent': 'your-agent-name/version'  // e.g., 'ably-cli/0.7.7'
  }
});
  1. Agent Naming Conventions
  • Use lowercase kebab-case for agent names (e.g., ably-cli, my-integration)
  • Include version numbers in semantic versioning format (e.g., 1.2.3)
  • For wrappers/tools, use descriptive names that indicate the tool's purpose
  1. Adding to agents.json

To officially register your agent, add it to agents.json:

{
  "identifier": "your-agent-name",
  "versioned": true,
  "type": "wrapper"  // or "tool", "integration", etc.
}
  1. Testing Agent Headers
  • For SDK usage: The agent will be automatically included in all REST and WebSocket requests
  • For HTTP requests: Verify the header is present using network inspection tools
  • Consider adding tests to ensure the agent header is included correctly
  1. Version Management
  • Consider reading version from your local package
  • For compiled/distributed tools, you may need to hardcode the version
  • Remember to update the version when releasing new versions of your tool