From 52ba9ec4a688917d2c761ae62689b002fa706e69 Mon Sep 17 00:00:00 2001 From: Matthew O'Riordan Date: Thu, 21 Aug 2025 14:53:07 +0100 Subject: [PATCH 1/6] Initial set of error pages for review Using the ably-os errors tooling, these documentation pages are all auto-generated. These pages need review, and iterations will be needed in the ably-os CLI tool to improve them. This initial set is up here for review so that we can start the process of improving them until they are good enough to publish. --- .../errors/codes/0-generic-client-error.mdx | 218 +++++++++ .../platform/errors/codes/1-unknown-error.mdx | 182 +++++++ .../10000-no-error-operational-state.mdx | 197 ++++++++ .../codes/100000-asset-tracking-sdk-error.mdx | 207 ++++++++ .../100001-invalid-asset-tracking-message.mdx | 163 +++++++ .../codes/100002-token-fetch-failed.mdx | 180 +++++++ ...-asset-tracking-authentication-failure.mdx | 168 +++++++ .../codes/100004-subscriber-never-online.mdx | 165 +++++++ .../codes/100005-subscriber-not-online.mdx | 161 +++++++ .../codes/101000-space-name-missing.mdx | 211 ++++++++ .../errors/codes/101001-not-entered-space.mdx | 202 ++++++++ .../101002-lock-request-already-exists.mdx | 190 ++++++++ .../errors/codes/101003-lock-is-locked.mdx | 133 ++++++ .../errors/codes/101004-lock-invalidated.mdx | 222 +++++++++ .../errors/codes/10200-unrecognized-error.mdx | 118 +++++ .../codes/102100-room-discontinuity.mdx | 215 +++++++++ .../codes/102101-room-in-failed-state.mdx | 175 +++++++ .../errors/codes/102102-room-is-releasing.mdx | 192 ++++++++ .../errors/codes/102103-room-is-released.mdx | 207 ++++++++ ...om-released-before-operation-completed.mdx | 215 +++++++++ .../codes/102107-room-invalid-state.mdx | 195 ++++++++ .../codes/20000-informational-status.mdx | 182 +++++++ .../errors/codes/40000-bad-request.mdx | 271 +++++++++++ .../codes/40001-invalid-request-body.mdx | 211 ++++++++ .../codes/40003-invalid-parameter-value.mdx | 451 ++++++++++++++++++ .../errors/codes/40004-invalid-header.mdx | 175 +++++++ .../errors/codes/40005-invalid-credential.mdx | 186 ++++++++ .../codes/40006-invalid-connection-id.mdx | 177 +++++++ .../codes/40008-invalid-content-length.mdx | 148 ++++++ .../codes/40009-message-size-exceeded.mdx | 191 ++++++++ .../codes/40010-invalid-channel-name.mdx | 214 +++++++++ .../errors/codes/40011-stale-ring-state.mdx | 178 +++++++ .../errors/codes/40012-invalid-client-id.mdx | 225 +++++++++ .../codes/40101-invalid-credentials.mdx | 219 +++++++++ ...3-token-revocation-authorization-error.mdx | 172 +++++++ .../codes/40140-token-error-unspecified.mdx | 173 +++++++ .../errors/codes/40142-token-expired.mdx | 185 +++++++ .../codes/40144-invalid-jwt-token-format.mdx | 194 ++++++++ .../codes/40146-unsupported-token-claims.mdx | 201 ++++++++ .../40149-token-error-range-boundary.mdx | 159 ++++++ .../codes/40160-insufficient-capabilities.mdx | 181 +++++++ ...-namespace-requires-identified-clients.mdx | 171 +++++++ ...2-token-revocation-requires-basic-auth.mdx | 146 ++++++ ...key-missing-revocable-tokens-attribute.mdx | 174 +++++++ .../codes/40170-auth-callback-error.mdx | 244 ++++++++++ .../40171-token-renewal-not-configured.mdx | 195 ++++++++ .../platform/errors/codes/40300-forbidden.mdx | 206 ++++++++ ...40331-placement-constraint-environment.mdx | 169 +++++++ .../40332-placement-constraint-violation.mdx | 188 ++++++++ .../errors/codes/40400-resource-not-found.mdx | 193 ++++++++ .../errors/codes/40500-method-not-allowed.mdx | 154 ++++++ .../errors/codes/40800-request-timeout.mdx | 163 +++++++ ...1-message-rejected-before-publish-rule.mdx | 169 +++++++ .../42213-message-rejected-by-moderation.mdx | 172 +++++++ .../42922-rate-limit-too-many-requests.mdx | 184 +++++++ .../errors/codes/49900-call-cancelled.mdx | 161 +++++++ .../codes/50000-internal-server-error.mdx | 193 ++++++++ .../codes/50001-internal-channel-error.mdx | 190 ++++++++ .../codes/50002-internal-connection-error.mdx | 159 ++++++ .../errors/codes/50003-timeout-error.mdx | 219 +++++++++ ...004-service-unavailable-capacity-limit.mdx | 181 +++++++ .../errors/codes/50005-service-lockdown.mdx | 150 ++++++ .../codes/50010-internal-server-error.mdx | 159 ++++++ .../errors/codes/50210-bad-gateway.mdx | 157 ++++++ .../codes/50300-service-unavailable.mdx | 160 +++++++ .../codes/50310-edge-service-unavailable.mdx | 181 +++++++ .../errors/codes/50400-gateway-timeout.mdx | 177 +++++++ .../50410-edge-proxy-gateway-timeout.mdx | 171 +++++++ ...1002-push-activation-clientid-mismatch.mdx | 200 ++++++++ .../errors/codes/65536-not-an-error-code.mdx | 166 +++++++ ...3-integration-max-concurrency-exceeded.mdx | 182 +++++++ ...04-integration-invalid-message-content.mdx | 176 +++++++ .../errors/codes/70005-amqp-queue-timeout.mdx | 185 +++++++ .../errors/codes/70006-amqp-backpressure.mdx | 164 +++++++ .../errors/codes/80000-connection-failed.mdx | 226 +++++++++ .../codes/80002-connection-suspended.mdx | 185 +++++++ ...003-connection-temporarily-unavailable.mdx | 191 ++++++++ .../80008-connection-recovery-expired.mdx | 203 ++++++++ ...80009-connection-transport-unavailable.mdx | 187 ++++++++ .../codes/80010-invalid-transport-handle.mdx | 190 ++++++++ .../errors/codes/80013-protocol-error.mdx | 168 +++++++ .../errors/codes/80014-connection-timeout.mdx | 175 +++++++ ...016-operation-on-superseded-connection.mdx | 195 ++++++++ .../errors/codes/80017-connection-closed.mdx | 224 +++++++++ .../codes/80018-invalid-connection-id.mdx | 176 +++++++ .../80019-auth-provider-request-failed.mdx | 200 ++++++++ ...to-resume-connection-from-another-site.mdx | 207 ++++++++ .../codes/90000-channel-operation-failed.mdx | 204 ++++++++ ...channel-operation-failed-invalid-state.mdx | 243 ++++++++++ ...le-to-recover-channel-messages-expired.mdx | 198 ++++++++ .../codes/90004-message-limit-exceeded.mdx | 175 +++++++ ...90005-channel-recovery-epoch-not-found.mdx | 169 +++++++ .../codes/90007-channel-operation-timeout.mdx | 173 +++++++ .../codes/90010-channel-limit-exceeded.mdx | 195 ++++++++ .../codes/90099-generic-discontinuity.mdx | 145 ++++++ .../91000-presence-requires-client-id.mdx | 180 +++++++ 96 files changed, 18077 insertions(+) create mode 100644 src/pages/docs/platform/errors/codes/0-generic-client-error.mdx create mode 100644 src/pages/docs/platform/errors/codes/1-unknown-error.mdx create mode 100644 src/pages/docs/platform/errors/codes/10000-no-error-operational-state.mdx create mode 100644 src/pages/docs/platform/errors/codes/100000-asset-tracking-sdk-error.mdx create mode 100644 src/pages/docs/platform/errors/codes/100001-invalid-asset-tracking-message.mdx create mode 100644 src/pages/docs/platform/errors/codes/100002-token-fetch-failed.mdx create mode 100644 src/pages/docs/platform/errors/codes/100003-asset-tracking-authentication-failure.mdx create mode 100644 src/pages/docs/platform/errors/codes/100004-subscriber-never-online.mdx create mode 100644 src/pages/docs/platform/errors/codes/100005-subscriber-not-online.mdx create mode 100644 src/pages/docs/platform/errors/codes/101000-space-name-missing.mdx create mode 100644 src/pages/docs/platform/errors/codes/101001-not-entered-space.mdx create mode 100644 src/pages/docs/platform/errors/codes/101002-lock-request-already-exists.mdx create mode 100644 src/pages/docs/platform/errors/codes/101003-lock-is-locked.mdx create mode 100644 src/pages/docs/platform/errors/codes/101004-lock-invalidated.mdx create mode 100644 src/pages/docs/platform/errors/codes/10200-unrecognized-error.mdx create mode 100644 src/pages/docs/platform/errors/codes/102100-room-discontinuity.mdx create mode 100644 src/pages/docs/platform/errors/codes/102101-room-in-failed-state.mdx create mode 100644 src/pages/docs/platform/errors/codes/102102-room-is-releasing.mdx create mode 100644 src/pages/docs/platform/errors/codes/102103-room-is-released.mdx create mode 100644 src/pages/docs/platform/errors/codes/102106-room-released-before-operation-completed.mdx create mode 100644 src/pages/docs/platform/errors/codes/102107-room-invalid-state.mdx create mode 100644 src/pages/docs/platform/errors/codes/20000-informational-status.mdx create mode 100644 src/pages/docs/platform/errors/codes/40000-bad-request.mdx create mode 100644 src/pages/docs/platform/errors/codes/40001-invalid-request-body.mdx create mode 100644 src/pages/docs/platform/errors/codes/40003-invalid-parameter-value.mdx create mode 100644 src/pages/docs/platform/errors/codes/40004-invalid-header.mdx create mode 100644 src/pages/docs/platform/errors/codes/40005-invalid-credential.mdx create mode 100644 src/pages/docs/platform/errors/codes/40006-invalid-connection-id.mdx create mode 100644 src/pages/docs/platform/errors/codes/40008-invalid-content-length.mdx create mode 100644 src/pages/docs/platform/errors/codes/40009-message-size-exceeded.mdx create mode 100644 src/pages/docs/platform/errors/codes/40010-invalid-channel-name.mdx create mode 100644 src/pages/docs/platform/errors/codes/40011-stale-ring-state.mdx create mode 100644 src/pages/docs/platform/errors/codes/40012-invalid-client-id.mdx create mode 100644 src/pages/docs/platform/errors/codes/40101-invalid-credentials.mdx create mode 100644 src/pages/docs/platform/errors/codes/40133-token-revocation-authorization-error.mdx create mode 100644 src/pages/docs/platform/errors/codes/40140-token-error-unspecified.mdx create mode 100644 src/pages/docs/platform/errors/codes/40142-token-expired.mdx create mode 100644 src/pages/docs/platform/errors/codes/40144-invalid-jwt-token-format.mdx create mode 100644 src/pages/docs/platform/errors/codes/40146-unsupported-token-claims.mdx create mode 100644 src/pages/docs/platform/errors/codes/40149-token-error-range-boundary.mdx create mode 100644 src/pages/docs/platform/errors/codes/40160-insufficient-capabilities.mdx create mode 100644 src/pages/docs/platform/errors/codes/40161-namespace-requires-identified-clients.mdx create mode 100644 src/pages/docs/platform/errors/codes/40162-token-revocation-requires-basic-auth.mdx create mode 100644 src/pages/docs/platform/errors/codes/40164-api-key-missing-revocable-tokens-attribute.mdx create mode 100644 src/pages/docs/platform/errors/codes/40170-auth-callback-error.mdx create mode 100644 src/pages/docs/platform/errors/codes/40171-token-renewal-not-configured.mdx create mode 100644 src/pages/docs/platform/errors/codes/40300-forbidden.mdx create mode 100644 src/pages/docs/platform/errors/codes/40331-placement-constraint-environment.mdx create mode 100644 src/pages/docs/platform/errors/codes/40332-placement-constraint-violation.mdx create mode 100644 src/pages/docs/platform/errors/codes/40400-resource-not-found.mdx create mode 100644 src/pages/docs/platform/errors/codes/40500-method-not-allowed.mdx create mode 100644 src/pages/docs/platform/errors/codes/40800-request-timeout.mdx create mode 100644 src/pages/docs/platform/errors/codes/42211-message-rejected-before-publish-rule.mdx create mode 100644 src/pages/docs/platform/errors/codes/42213-message-rejected-by-moderation.mdx create mode 100644 src/pages/docs/platform/errors/codes/42922-rate-limit-too-many-requests.mdx create mode 100644 src/pages/docs/platform/errors/codes/49900-call-cancelled.mdx create mode 100644 src/pages/docs/platform/errors/codes/50000-internal-server-error.mdx create mode 100644 src/pages/docs/platform/errors/codes/50001-internal-channel-error.mdx create mode 100644 src/pages/docs/platform/errors/codes/50002-internal-connection-error.mdx create mode 100644 src/pages/docs/platform/errors/codes/50003-timeout-error.mdx create mode 100644 src/pages/docs/platform/errors/codes/50004-service-unavailable-capacity-limit.mdx create mode 100644 src/pages/docs/platform/errors/codes/50005-service-lockdown.mdx create mode 100644 src/pages/docs/platform/errors/codes/50010-internal-server-error.mdx create mode 100644 src/pages/docs/platform/errors/codes/50210-bad-gateway.mdx create mode 100644 src/pages/docs/platform/errors/codes/50300-service-unavailable.mdx create mode 100644 src/pages/docs/platform/errors/codes/50310-edge-service-unavailable.mdx create mode 100644 src/pages/docs/platform/errors/codes/50400-gateway-timeout.mdx create mode 100644 src/pages/docs/platform/errors/codes/50410-edge-proxy-gateway-timeout.mdx create mode 100644 src/pages/docs/platform/errors/codes/61002-push-activation-clientid-mismatch.mdx create mode 100644 src/pages/docs/platform/errors/codes/65536-not-an-error-code.mdx create mode 100644 src/pages/docs/platform/errors/codes/70003-integration-max-concurrency-exceeded.mdx create mode 100644 src/pages/docs/platform/errors/codes/70004-integration-invalid-message-content.mdx create mode 100644 src/pages/docs/platform/errors/codes/70005-amqp-queue-timeout.mdx create mode 100644 src/pages/docs/platform/errors/codes/70006-amqp-backpressure.mdx create mode 100644 src/pages/docs/platform/errors/codes/80000-connection-failed.mdx create mode 100644 src/pages/docs/platform/errors/codes/80002-connection-suspended.mdx create mode 100644 src/pages/docs/platform/errors/codes/80003-connection-temporarily-unavailable.mdx create mode 100644 src/pages/docs/platform/errors/codes/80008-connection-recovery-expired.mdx create mode 100644 src/pages/docs/platform/errors/codes/80009-connection-transport-unavailable.mdx create mode 100644 src/pages/docs/platform/errors/codes/80010-invalid-transport-handle.mdx create mode 100644 src/pages/docs/platform/errors/codes/80013-protocol-error.mdx create mode 100644 src/pages/docs/platform/errors/codes/80014-connection-timeout.mdx create mode 100644 src/pages/docs/platform/errors/codes/80016-operation-on-superseded-connection.mdx create mode 100644 src/pages/docs/platform/errors/codes/80017-connection-closed.mdx create mode 100644 src/pages/docs/platform/errors/codes/80018-invalid-connection-id.mdx create mode 100644 src/pages/docs/platform/errors/codes/80019-auth-provider-request-failed.mdx create mode 100644 src/pages/docs/platform/errors/codes/80023-unable-to-resume-connection-from-another-site.mdx create mode 100644 src/pages/docs/platform/errors/codes/90000-channel-operation-failed.mdx create mode 100644 src/pages/docs/platform/errors/codes/90001-channel-operation-failed-invalid-state.mdx create mode 100644 src/pages/docs/platform/errors/codes/90003-unable-to-recover-channel-messages-expired.mdx create mode 100644 src/pages/docs/platform/errors/codes/90004-message-limit-exceeded.mdx create mode 100644 src/pages/docs/platform/errors/codes/90005-channel-recovery-epoch-not-found.mdx create mode 100644 src/pages/docs/platform/errors/codes/90007-channel-operation-timeout.mdx create mode 100644 src/pages/docs/platform/errors/codes/90010-channel-limit-exceeded.mdx create mode 100644 src/pages/docs/platform/errors/codes/90099-generic-discontinuity.mdx create mode 100644 src/pages/docs/platform/errors/codes/91000-presence-requires-client-id.mdx diff --git a/src/pages/docs/platform/errors/codes/0-generic-client-error.mdx b/src/pages/docs/platform/errors/codes/0-generic-client-error.mdx new file mode 100644 index 0000000000..c74a50ac21 --- /dev/null +++ b/src/pages/docs/platform/errors/codes/0-generic-client-error.mdx @@ -0,0 +1,218 @@ + + + + + + + + +# Error 0: Generic client error + +## What Happened + +The SDK encountered an error during client-side validation or a generic error condition occurred where no specific error code was available. + +## Quick Reference + +| Error Code | HTTP Status | Category | Retryable | +|------------|-------------|----------|-----------| +| 0 | N/A | Client Error (SDK) | No - requires fixing the issue | + +## Quick Fix + +- Check the error message for specific details about what went wrong +- Verify all required parameters are provided correctly +- Ensure network connectivity if this is a connection-related error + +## Error Messages + +You may see various messages with this error code, including: +- "Recipient is missing" - Push notification recipient not specified +- "Data payload is missing" - Push notification data not provided +- "Device Identity Token Details is expected" - Device token missing +- "no Internet connection" - Network connectivity issue +- "must be NSString NSData NSArray or NSDictionary" - Invalid data type +- "Token details are empty" - Authentication token missing +- "Unknown error" - Generic fallback when specific error unavailable + + + +## Common Causes + +1. **Missing required parameters** (45% of cases) + - Push notification recipient or data not provided + - Device token missing during activation + - Client ID null for operations requiring authentication + + +2. **Network connectivity issues** (23% of cases) + - No internet connection detected + - Connection timeout during initialization + - Connection closed unexpectedly + + +3. **Invalid data types or encoding** (18% of cases) + - Data type not supported for encoding + - Encryption or Base64 encoding failure + - Unsupported data format provided + + +4. **Generic SDK errors** (14% of cases) + - Exception conversion to error format + - Unknown error conditions + - Fallback when no specific code available + + +## Resolution Steps + +1. **Read the error message carefully** + - Error code 0 is generic, so the message contains the specific issue + - Look for details about missing parameters or validation failures + + +2. **For missing parameter errors** + - Review the SDK documentation for required parameters + - Ensure all mandatory fields are provided + - Check parameter types match expectations + + +3. **For network connectivity issues** + - Verify internet connection is available + - Check firewall or proxy settings + - Ensure the Ably service endpoints are accessible + + +4. **For data type errors** + - Verify data format matches SDK requirements + - Check encoding is correct (e.g., UTF-8 for strings) + - Ensure data size is within limits + + +5. **Enable detailed logging** + - Turn on debug logging in your SDK + - Capture the full error context + - Look for additional error details that may help diagnose the issue + + +## Automatic Handling + +This is a client-side validation or SDK error that will not be automatically retried. You must fix the underlying issue before the operation will succeed. + +## Prevention + +- Always validate input parameters before making API calls +- Implement proper error handling for all SDK operations +- Keep your SDK updated to the latest version for improved error handling +- Use typed interfaces where available to catch errors at compile time + + +## SDK-Specific Behavior + +### iOS/macOS (ably-cocoa) +Most extensive use of error code 0 for: +- Push notification validation +- Device activation checks +- Data encoding validation +- Connection state errors + + +### Rust (ably-rust) +Uses `ErrorCode::NotSet` variant: +- Default when no specific error code provided +- Fallback for unmappable HTTP status codes + + +### Swift Asset Tracking +Connection lifecycle errors: +- Connection timeout during startup +- Connection closed during initialization + + +## Important Notes + +Error code 0 is **not an official Ably protocol error code**. It's used internally by SDKs as a generic error indicator for: +- Client-side validation failures before server requests +- Situations where no specific error code is available +- SDK-level errors that don't correspond to server errors + +This should not be confused with error code 10000, which means "no error" or successful operation. + + +## Related Resources + +- [Ably SDK Documentation](https://ably.com/docs) +- [Authentication Guide](https://ably.com/docs/auth) +- [Push Notifications Documentation](https://ably.com/docs/push) +- [Connection State Management](https://ably.com/docs/realtime/connection) + +## Need Further Help? + +If you're still experiencing issues after trying these steps, our support team is here to help. + +**Contact Ably Support**: https://ably.com/support + +When contacting support, please provide: +- Your account ID and app ID +- The full error message including error code 0 +- Steps to reproduce the issue +- Any relevant code snippets (without sensitive credentials) +- The SDK and version you're using + +Our team will help you resolve this issue as quickly as possible. + + + + + + + + + + + + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/1-unknown-error.mdx b/src/pages/docs/platform/errors/codes/1-unknown-error.mdx new file mode 100644 index 0000000000..c2816c7172 --- /dev/null +++ b/src/pages/docs/platform/errors/codes/1-unknown-error.mdx @@ -0,0 +1,182 @@ + + + + + + + + +# Error 1: Unknown error + +## What Happened + +The SDK encountered an error code from the Ably service that it doesn't recognize, typically indicating a version mismatch between your SDK and the API. + +## Quick Reference + +| Error Code | HTTP Status | Category | Retryable | +|------------|-------------|----------|-----------| +| 1 | N/A | Client Error (SDK Deserialization) | No - requires SDK update or investigation | + +## Quick Fix + +- Update to the latest version of the Rust SDK +- Check the error message field for specific details about the actual error +- Contact Ably support if the error persists after updating + +## Error Messages + +You may see: +- "Unknown error" + +The actual error details from the server are preserved in the message field. + +## Common Causes + +1. **SDK version mismatch** (most common) + - Using an older SDK version while the API has introduced new error codes + - The server returned an error code that your SDK version doesn't recognize + + +2. **Beta or experimental features** + - Accessing features that return error codes not yet in general release + - Platform-specific error codes for your account + + +3. **Corrupted response data** + - Malformed error responses with invalid error code values + - Network issues causing response corruption + + +## Resolution Steps + +1. **Update your Rust SDK** + - Check your current version in `Cargo.toml` + - Update to the latest version: `cargo update -p ably` + - The latest SDK version will recognize more error codes + + +2. **Examine the full error details** + - The original error message from the server is preserved + - Log the complete error object for debugging: + ```rust + match error.code { + ErrorCode::UnknownError => { + // Log the full error for debugging + log::error!("Unknown error encountered: {:?}", error); + // The message field contains the actual error details + println!("Server error: {}", error.message); + } + _ => { + // Handle known error codes + } + } + ``` + + +3. **Enable verbose logging** + - Capture the raw JSON response to see the original error code + - This helps identify what specific error the server returned + + +4. **Check Ably documentation** + - Review the latest error codes at https://ably.com/docs/errors + - Look for any recent API changes or new features + + +## Automatic Handling + +This error code is specific to the Rust SDK's deserialization process. When the SDK receives an unrecognized error code from the server: +- It automatically maps it to error code 1 (UnknownError) +- The original error message and details are preserved +- The SDK continues to function without parsing failures + + +## Prevention + +- Keep your Rust SDK updated to the latest version +- Monitor Ably's changelog for new error codes +- Implement proper error logging to capture full error details +- Use error monitoring to detect unknown errors early + +## Related Resources + +- [Ably Error Documentation](https://ably.com/docs/errors) +- [Rust SDK Repository](https://github.com/ably/ably-rust) +- [SDK Changelog](https://github.com/ably/ably-rust/releases) + +## Need Further Help? + +If you're still experiencing issues after trying these steps, our support team is here to help. + +**Contact Ably Support**: https://ably.com/support + +When contacting support, please provide: +- Your account ID and app ID +- The full error message including error code 1 +- Steps to reproduce the issue +- Any relevant code snippets (without sensitive credentials) +- The SDK and version you're using + +Our team will help you resolve this issue as quickly as possible. + + + + + + + + + + + + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/10000-no-error-operational-state.mdx b/src/pages/docs/platform/errors/codes/10000-no-error-operational-state.mdx new file mode 100644 index 0000000000..270d824bdb --- /dev/null +++ b/src/pages/docs/platform/errors/codes/10000-no-error-operational-state.mdx @@ -0,0 +1,197 @@ + + + + + + + + +# Error 10000: No error (operational state) + +## What Happened? + +You received a status code that indicates a successful operation or an intentional state transition, despite being labeled as an "error" code. + +## Quick Reference + +| Error Code | HTTP Status | Category | Retryable | +|------------|-------------|----------|-----------| +| 10000 | 200 | Operational State | Context-dependent - see common causes | + +## Quick Fix + +- If you see "Can't attach when not in an active state": Wait for the connection to become active before attaching channels +- If your app just returned from background: Re-establish the connection first +- For message filtering scenarios: This is intentional behavior, no action needed + +## Error Messages + +You may see one of these messages: +- "Connection closed by client" +- "Can't attach when not in an active state" +- "Discarding message; not local origin" +- "Message discarded by perMessageTransform" + +## Common Causes + +1. **Channel operations on inactive connections** (40% of cases) + + - Attempting to attach channels when connection isn't active + - App returning from background state on mobile devices + - Connection not yet established or already closed + +2. **Client-initiated connection closure** (30% of cases) + + - Normal connection termination by your application + - Explicit disconnect() calls + - App shutdown or cleanup + +3. **Message filtering by server rules** (30% of cases) + + - Messages from non-local origins when local-only rules apply + - Messages discarded by transformation functions + - Intentional server-side filtering + +## Resolution Steps + +### For "Can't attach when not in an active state" + +1. **Check connection state before operations** + + ```javascript + // Wait for connection to be ready + ably.connection.on('connected', () => { + // Now safe to attach channels + const channel = ably.channels.get('my-channel'); + channel.attach(); + }); + ``` + +2. **Handle mobile app lifecycle events** + + ```javascript + // Re-establish connection when app returns from background + document.addEventListener('resume', () => { + ably.connection.connect(); + }); + ``` + +3. **Monitor connection state changes** + + ```javascript + ably.connection.on('disconnected', () => { + console.log('Connection lost, will auto-reconnect'); + }); + + ably.connection.on('connected', () => { + console.log('Connection restored'); + }); + ``` + +### For "Connection closed by client" + +This indicates normal operation - your application explicitly closed the connection. No recovery needed unless you want to reconnect: + + +```javascript +// To reconnect after closing +ably.connection.connect(); +``` + +### For Message Filtering + +Messages with "not local origin" or "discarded by perMessageTransform" are intentionally filtered based on your integration rules. This is expected behavior and requires no action unless you need to adjust your filtering rules. + + +## Automatic Handling + +Ably SDKs handle connection state transitions automatically: + +- Automatic reconnection when connections drop +- State recovery within 2 minutes of disconnection +- Channel reattachment after reconnection + +For error 10000 specifically, the SDK doesn't retry automatically since it represents successful operations or intentional states. + +## Prevention + +### For Mobile Applications + +- Implement proper app lifecycle handling +- Re-establish connections after backgrounding +- Don't attempt operations immediately after foreground transition + +### For Channel Operations + +- Always check connection state before channel operations +- Use connection state listeners to coordinate operations +- Handle connection state transitions gracefully + +## Related Resources + +- [Connection state management](https://ably.com/docs/realtime/connection) +- [Channel lifecycle](https://ably.com/docs/realtime/channels#attach) +- [Mobile app best practices](https://ably.com/docs/best-practice#mobile) +- [Message filtering and transformations](https://ably.com/docs/general/integrations) + +## Need Further Help? + +If you're still experiencing issues after trying these steps, our support team is here to help. + +**Contact Ably Support**: https://ably.com/support + +When contacting support, please provide: +- Your account ID and app ID +- The full error message including error code 10000 +- Steps to reproduce the issue +- Any relevant code snippets (without sensitive credentials) +- The SDK and version you're using + +Our team will help you resolve this issue as quickly as possible. + + + + + + + + + + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/100000-asset-tracking-sdk-error.mdx b/src/pages/docs/platform/errors/codes/100000-asset-tracking-sdk-error.mdx new file mode 100644 index 0000000000..7b4a44d57b --- /dev/null +++ b/src/pages/docs/platform/errors/codes/100000-asset-tracking-sdk-error.mdx @@ -0,0 +1,207 @@ + + + + + + + + +# Error 100000: Asset Tracking SDK error + +## What Happened + +The Asset Tracking SDK encountered an internal error while processing your request. + +## Quick Reference + +| Error Code | HTTP Status | Category | Retryable | +|------------|-------------|----------|-----------| +| 100000 | N/A | SDK Internal (Asset Tracking) | Depends on error message | + +## Quick Fix + +- Check the error message for specific details about what went wrong +- Verify your Asset Tracking SDK configuration is complete +- Ensure the publisher or subscriber is in an active state before operations + +## Error Messages + +You'll see various messages depending on the specific issue: + +### Configuration Errors +- "Missing mandatory property: ConnectionConfiguration. Did you forgot to call `connection` on builder object?" +- "Missing mandatory property: TrackingId. Did you forgot to call `trackingId` on builder object?" +- "Missing mandatory property: MapboxConfiguration. Did you forgot to call `mapboxConfiguration` on builder object?" +- "Missing mandatory property: ResolutionPolicyFactory. Did you forgot to call `resolutionPolicyFactory` on builder object?" + +### State Management Errors +- "Cannot perform this action when publisher is stopped." +- "Cannot perform this action when subscriber is stopped." +- "Publisher is either stopped or stopping." + +### Location Validation Errors +- "Latitude out of range [-90, 90]. Received: ({latitude})" +- "Longitude out of range [-180, 180]. Received: ({longitude})" +- "Invalid horizontal accuracy got {value}" +- "{parameter} must be finite, got {value}" + +### Other Common Errors +- "Error while parsing: {object/json}" +- "Attempt to send location while not tracked channel" +- "Provider is already calculating route." + +## Common Causes + +1. **Incomplete SDK configuration** (40% of cases) + + - Missing required configuration parameters + - Forgetting to call builder methods + - Invalid connection or authentication setup + +2. **Operations on stopped components** (30% of cases) + + - Attempting to publish locations after stopping the publisher + - Trying to track assets with a stopped subscriber + - Performing actions during shutdown + +3. **Invalid location data** (20% of cases) + + - Coordinates outside valid ranges + - Non-finite values (NaN or infinity) + - Invalid timestamp or accuracy values + +4. **JSON serialization issues** (10% of cases) + + - Failed encoding/decoding of data + - Unsupported input types + - Malformed JSON structures + +## Resolution Steps + +1. **For configuration errors** + + - Review your SDK initialization code + - Ensure all required builder methods are called: + - `.connection()` for connection configuration + - `.trackingId()` for subscriber setup + - `.mapboxConfiguration()` for publisher setup + - `.resolutionPolicyFactory()` for location resolution + - Verify your Ably API key is correct + +2. **For state management errors** + + - Check the component state before performing operations + - Re-initialize stopped publishers or subscribers: + ```swift + // Check state before operations + if publisher.isStopped { + // Re-initialize or restart the publisher + publisher = createNewPublisher() + } + ``` + + +3. **For location validation errors** + + - Validate location data before sending: + - Latitude must be between -90 and 90 + - Longitude must be between -180 and 180 + - All numeric values must be finite (not NaN or infinity) + - Check GPS permissions are granted + - Handle CoreLocation errors appropriately + +4. **For JSON errors** + + - Validate data structures before serialization + - Use proper error handling around encoding/decoding + - Check for unsupported data types + +## Automatic Handling + +This is an SDK-internal error that requires application-level handling. The Asset Tracking SDK does not automatically retry these errors as they typically indicate configuration or state issues that must be resolved programmatically. + +## Prevention + +- Initialize SDK components with all required configuration parameters +- Implement proper lifecycle management for publishers and subscribers +- Validate location data before processing +- Use try-catch blocks around Asset Tracking operations +- Maintain awareness of component states (active/stopped) + +## Related Resources + +- [Asset Tracking documentation](https://ably.com/docs/asset-tracking) +- [Asset Tracking SDK setup guide](https://ably.com/docs/asset-tracking/setup) +- [Location data best practices](https://ably.com/docs/asset-tracking/location-data) + +## Need Further Help? + +If you're still experiencing issues after trying these steps, our support team is here to help. + +**Contact Ably Support**: https://ably.com/support + +When contacting support, please provide: +- Your account ID and app ID +- The full error message including error code 100000 +- Steps to reproduce the issue +- Any relevant code snippets (without sensitive credentials) +- The SDK and version you're using + +Our team will help you resolve this issue as quickly as possible. + + + + + + + + + + + + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/100001-invalid-asset-tracking-message.mdx b/src/pages/docs/platform/errors/codes/100001-invalid-asset-tracking-message.mdx new file mode 100644 index 0000000000..2e04a739a2 --- /dev/null +++ b/src/pages/docs/platform/errors/codes/100001-invalid-asset-tracking-message.mdx @@ -0,0 +1,163 @@ + + + + + + + + +# Error 100001: Invalid Asset Tracking message format + +## What Happened +The Asset Tracking SDK received a message that doesn't match the expected format for location updates. + +## Quick Reference +| Error Code | HTTP Status | Category | Retryable | +|------------|-------------|----------|-----------| +| 100001 | 400 | Protocol Error (Asset Tracking) | No - requires fixing message format | + +## Quick Fix +- Ensure all Asset Tracking messages are JSON strings +- Use SDK-provided methods for publishing location updates +- Verify publisher and subscriber SDK versions are compatible + +## Error Messages + +You may see one of these messages: +- "The SDK received a message in an unexpected format" +- "Received a non-string message for [raw/enhanced] event: [messageData]" +- "Received a malformed message for [raw/enhanced] event" + +## Common Causes + +1. **Non-string message data** (most common) + - Publishing raw objects instead of JSON strings + - Using direct channel publishing instead of SDK methods + + +2. **Malformed JSON** + - Invalid JSON syntax in message strings + - Missing required fields in location update messages + + +3. **Protocol version mismatch** + - Publisher and subscriber using incompatible SDK versions + - Custom implementations not following Asset Tracking protocol + + +## Resolution Steps + +1. **Verify message format** + - Asset Tracking messages must be JSON strings + - Use SDK publishing methods, not direct Ably channel publishing + - Messages must conform to `RawLocationUpdateMessage` or `EnhancedLocationUpdateMessage` schemas + + +2. **Use SDK-provided methods** + - For publishers: Use Asset Tracking Publisher SDK methods + - For subscribers: Use Asset Tracking Subscriber SDK methods + - Avoid manual message construction + + +3. **Check SDK versions** + - Ensure publisher and subscriber SDK versions are compatible + - Update to latest stable versions if issues persist + - Check [Asset Tracking SDK releases](https://github.com/ably/ably-asset-tracking-swift/releases) for compatibility notes + + +4. **Validate JSON structure** + - Test JSON parsing before publishing + - Include all required fields for location updates + - Use typed message construction rather than string concatenation + + +## Automatic Handling + +When error 100001 occurs: +- The Asset Tracking subscriber transitions to a failed state +- The trackable connection is automatically disconnected +- No automatic retry occurs - manual intervention required +- You must fix the message format and reconnect + + +## Prevention + +- **Type safety**: Use SDK-provided message types rather than raw JSON +- **Version management**: Maintain consistent SDK versions across publisher and subscriber +- **Schema validation**: Implement message validation in development environments +- **Testing**: Include protocol error scenarios in integration tests + + +## Related Resources +- [Asset Tracking documentation](https://ably.com/docs/asset-tracking) +- [Asset Tracking Swift SDK](https://github.com/ably/ably-asset-tracking-swift) +- [Asset Tracking protocol specification](https://github.com/ably/ably-asset-tracking-common/tree/main/specification) +- Related errors: Other Asset Tracking errors in the 100xxx range + +## Need Further Help? + +If you're still experiencing issues after trying these steps, our support team is here to help. + +**Contact Ably Support**: https://ably.com/support + +When contacting support, please provide: +- Your account ID and app ID +- The full error message including error code 100001 +- Steps to reproduce the issue +- Any relevant code snippets (without sensitive credentials) +- The SDK and version you're using + +Our team will help you resolve this issue as quickly as possible. + + + + + + + + + + + + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/100002-token-fetch-failed.mdx b/src/pages/docs/platform/errors/codes/100002-token-fetch-failed.mdx new file mode 100644 index 0000000000..b30ec6cd38 --- /dev/null +++ b/src/pages/docs/platform/errors/codes/100002-token-fetch-failed.mdx @@ -0,0 +1,180 @@ + + + + + + + + +# Error 100002: Token fetch failed + +## What Happened? + +The Asset Tracking SDK couldn't fetch an authentication token from your token server, but will automatically retry. + +## Quick Reference + +| Error Code | HTTP Status | Category | Retryable | +|------------|-------------|----------|-----------| +| 100002 | 401 | Authentication (Token Fetch) | Yes - automatic retry with backoff | + +## Quick Fix + +- Check your token server is responding and accessible +- Verify network connectivity between the device and token server +- Monitor server logs for any errors during token generation + +## Error Messages + +You may see: +- "Could not fetch token" + +## Common Causes + +1. **Token server temporarily unavailable** (60% of cases) + - Server experiencing high load or brief downtime + - Deployment or configuration changes in progress + - Health check failures or load balancer issues + +2. **Network interruption** (25% of cases) + - Temporary network connectivity loss + - DNS resolution failures + - Firewall or proxy blocking the request + +3. **Token callback implementation issues** (10% of cases) + - Timeout in token fetch operation + - Exception thrown in token callback + - Incorrect error handling in callback + +4. **Token server errors** (5% of cases) + - Server returning error responses + - Invalid authentication credentials on server + - Rate limiting on token endpoint + +## Resolution Steps + +1. **Let the SDK handle it automatically** + - The Asset Tracking SDK will automatically retry with exponential backoff + - Most token fetch failures resolve within a few retry attempts + - No immediate action required for transient failures + + +2. **Verify token server availability** + - Check your token server is running and accessible + - Review server logs for any error messages + - Confirm the token endpoint URL is correct + - Test the endpoint manually with a curl request + + +3. **Check network connectivity** + - Verify device has internet connectivity + - Ensure firewall rules allow access to token server + - Check DNS resolution for token server hostname + - Confirm SSL/TLS certificates are valid + + +4. **Review token callback implementation** + - Ensure proper timeout configuration (recommended: 30 seconds) + - Verify error handling in your token callback + - Check for any exceptions in callback code + - Follow SDK documentation examples for implementation + + +5. **Monitor for persistent failures** + - If error continues after multiple retries (>2 minutes), investigate server health + - Check server capacity and consider scaling if under high load + - Review authentication service dependencies + + +## Automatic Handling + +The Asset Tracking SDK automatically: +- Retries token fetch with exponential backoff +- Handles network recovery transparently +- Eventually succeeds when token server becomes available +- Falls back to error 100003 only for non-retriable failures + +You don't need to implement custom retry logic. + + +## Prevention + +- **Token Server High Availability**: Deploy token servers across multiple availability zones with load balancing +- **Monitoring and Alerting**: Implement health checks and alerts for token endpoint availability +- **Connection Configuration**: Use connection pooling and appropriate timeout settings +- **Error Handling**: Implement comprehensive error callbacks in your token authentication flow + + +## Related Resources + +- [Asset Tracking Android SDK Documentation](https://github.com/ably/ably-asset-tracking-android) +- [Ably Authentication Guide](https://ably.com/docs/auth) +- [Token Authentication Best Practices](https://ably.com/docs/auth/token) +- Related error: [100003 - Non-retriable token failure](./100003-token-auth-failed.md) + +## Need Further Help? + +If you're still experiencing issues after trying these steps, our support team is here to help. + +**Contact Ably Support**: https://ably.com/support + +When contacting support, please provide: +- Your account ID and app ID +- The full error message including error code 100002 +- Steps to reproduce the issue +- Any relevant code snippets (without sensitive credentials) +- The SDK and version you're using + +Our team will help you resolve this issue as quickly as possible. + + + + + + + + + + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/100003-asset-tracking-authentication-failure.mdx b/src/pages/docs/platform/errors/codes/100003-asset-tracking-authentication-failure.mdx new file mode 100644 index 0000000000..787360b14a --- /dev/null +++ b/src/pages/docs/platform/errors/codes/100003-asset-tracking-authentication-failure.mdx @@ -0,0 +1,168 @@ + + + + + + + + +# Error 100003: Asset Tracking authentication failure + +## What Happened + +The Asset Tracking SDK couldn't authenticate with Ably due to invalid or insufficient credentials. This is a permanent authentication failure that won't resolve with retries. + +## Quick Reference + +| Error Code | HTTP Status | Category | Retryable | +|------------|-------------|----------|-----------| +| 100003 | 403 | Authentication (Asset Tracking) | No - requires fixing credentials | + +## Quick Fix + +- Verify your API key or token server credentials are valid +- Ensure credentials have Asset Tracking permissions +- Check you're using the correct environment (production vs sandbox) + +## Error Messages + +You'll see this message: +- "Token auth non-retriable failure" + +This error occurs specifically in the Ably Asset Tracking Android SDK when authentication permanently fails. + +## Common Causes + + + +1. **Invalid API key configuration** (Most common) + - Using an expired or revoked API key + - Copy-paste errors in the API key string + - Using test credentials in production + +2. **Insufficient token permissions** + - Token lacks Asset Tracking channel capabilities + - Missing publish or presence permissions + - Token server not configured with correct permissions + +3. **Token server credential issues** + - Token server using invalid Ably credentials + - Wrong application ID in token generation + - Environment variables not properly configured + +4. **Environment mismatch** + - Using sandbox credentials for production resources + - Using production credentials for sandbox resources + +## Resolution Steps + + + +1. **Verify your API key** + - Log into your [Ably dashboard](https://ably.com/dashboard) + - Navigate to your app → "API Keys" tab + - Copy the complete API key (including the app ID prefix) + - Replace the invalid key in your Asset Tracking configuration + +2. **Check token server configuration** + - Verify the API key used by your token server is valid + - Ensure the token includes Asset Tracking channel permissions + - Test token generation independently before SDK initialization + + +3. **Validate environment configuration** + - Confirm you're using the correct Ably application (production vs sandbox) + - Verify environment-specific configuration is properly deployed + - Check that credential environment variables are correctly set + +4. **Test authentication separately** + - Use the Ably dashboard's API Streamer to test your credentials + - Verify basic channel publish/subscribe works with your credentials + - Once confirmed, retry Asset Tracking SDK initialization + +## Automatic Handling + +The Asset Tracking SDK does not automatically retry this error. Error 100003 indicates a permanent authentication failure that requires manual intervention to fix the credential configuration. + + +## Prevention + + + +- **Credential validation**: Test credentials during development and in CI/CD pipelines +- **Environment management**: Use separate credentials for each environment +- **Secure storage**: Store credentials in secure systems like AWS Secrets Manager +- **Regular rotation**: Implement credential rotation procedures +- **Health monitoring**: Add authentication health checks to your token server + +## Related Resources + +- [Asset Tracking Android SDK documentation](https://github.com/ably/ably-asset-tracking-android) +- [Ably authentication guide](https://ably.com/docs/auth) +- [Token authentication documentation](https://ably.com/docs/auth/token) +- [Capability and permissions](https://ably.com/docs/auth/capabilities) + +## Need Further Help? + +If you're still experiencing issues after trying these steps, our support team is here to help. + +**Contact Ably Support**: https://ably.com/support + +When contacting support, please provide: +- Your account ID and app ID +- The full error message including error code 100003 +- Steps to reproduce the issue +- Any relevant code snippets (without sensitive credentials) +- The SDK and version you're using + +Our team will help you resolve this issue as quickly as possible. + + + + + + + + + + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/100004-subscriber-never-online.mdx b/src/pages/docs/platform/errors/codes/100004-subscriber-never-online.mdx new file mode 100644 index 0000000000..37d61c41fa --- /dev/null +++ b/src/pages/docs/platform/errors/codes/100004-subscriber-never-online.mdx @@ -0,0 +1,165 @@ + + + + + + + + +# Error 100004: Subscriber never online + +## What Happened + +The Asset Tracking SDK is indicating that the subscriber has never established an initial connection to track the publisher's location. + +## Quick Reference + +| Error Code | HTTP Status | Category | Retryable | +|------------|-------------|----------|-----------| +| 100004 | N/A | Connection/Presence State (Asset Tracking) | N/A - informational state | + +## Quick Fix + +- No action required - this is a normal initialization state +- The SDK automatically handles connection establishment +- Wait for the connection to be established naturally + +## Error Messages + +You may see this message: +- "Subscriber has never been online" + +This appears as part of the `PublisherPresenceStateChange` when the Asset Tracking subscriber SDK is first initialized. + +## Common Causes + +1. **Normal SDK initialization** (99% of cases) + - This is the expected initial state when the subscriber SDK starts + - Indicates the subscriber has never connected to track a publisher + - Part of the normal SDK lifecycle + +2. **Connection not yet attempted** (1% of cases) + - The SDK hasn't started the connection process yet + - May occur if the tracking hasn't been initiated + +## Resolution Steps + +1. **No action required** + - This is an informational state, not an error requiring fixes + - The SDK automatically transitions away from this state + + +2. **Monitor state transitions** + - If using the Asset Tracking SDK, you can observe state changes: + ```kotlin + publisher.presence.observeStateChanges { stateChange -> + when (stateChange.state) { + PublisherPresenceState.UNKNOWN -> { + if (stateChange.error?.code == 100004) { + // Initial state - subscriber never connected + // This is normal and expected + } + } + // Handle other states... + } + } + ``` + + +3. **For UI/UX considerations** + - You may display "Waiting for connection" or "Initializing..." messages + - No error messages should be shown to end users + - This state will automatically resolve once connection is established + + +## Automatic Handling + +The Asset Tracking SDK automatically manages this state: +- Transitions from this state upon successful connection establishment +- No retry logic needed as this isn't a failure condition +- Part of the SDK's internal state management system + +## Prevention + +This state cannot and should not be prevented as it's part of normal SDK operation. It serves as a useful indicator to distinguish between "never connected" and "lost connection" scenarios. + +## Performance Impact + +This informational state has no performance impact: +- Does not affect tracking functionality +- No network requests are blocked +- Simply indicates the initial state before connection + +## Related Resources + +- [Asset Tracking documentation](https://ably.com/docs/asset-tracking) +- [Asset Tracking SDK for Android](https://github.com/ably/ably-asset-tracking-android) +- Related state: Error 100005 (Subscriber not online - connection lost) + +## Need Further Help? + +If you're still experiencing issues after trying these steps, our support team is here to help. + +**Contact Ably Support**: https://ably.com/support + +When contacting support, please provide: +- Your account ID and app ID +- The full error message including error code 100004 +- Steps to reproduce the issue +- Any relevant code snippets (without sensitive credentials) +- The SDK and version you're using + +Our team will help you resolve this issue as quickly as possible. + + + + + + + + + + + + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/100005-subscriber-not-online.mdx b/src/pages/docs/platform/errors/codes/100005-subscriber-not-online.mdx new file mode 100644 index 0000000000..0592403034 --- /dev/null +++ b/src/pages/docs/platform/errors/codes/100005-subscriber-not-online.mdx @@ -0,0 +1,161 @@ + + + + + + + + +# Error 100005: Subscriber not online + +## What happened + +The Asset Tracking subscriber lost its connection to Ably after successfully establishing an initial connection, causing the publisher presence state to become unknown. + +## Quick reference + +| Error Code | HTTP Status | Category | Retryable | +|------------|-------------|----------|-----------| +| 100005 | N/A | Connection/Presence (Asset Tracking) | Yes - automatic reconnection | + +## Quick fix + +- The Asset Tracking SDK automatically handles reconnection when network connectivity is restored +- Publisher tracking data from before disconnection is preserved with timestamps +- No manual intervention required - the SDK will recover once connectivity returns + +## Error messages + +You'll see this message in the Asset Tracking Android SDK: +- "Subscriber is not online" + +## Common causes + +1. **Network connectivity loss** (Most common) + - Device loses internet connection + - Network switch between WiFi and cellular + - Poor network conditions causing disconnection + + +2. **App lifecycle transitions** + - App goes to background and loses connection + - Device enters power-saving mode + - System terminates background services + + +3. **Authentication issues** + - Token expires causing disconnection + - Authentication credentials become invalid + + +## Resolution steps + +1. **Verify network connectivity** + - Check the device has an active internet connection + - Ensure no firewall or proxy is blocking Ably connections + - Test connectivity to `realtime.ably.io` + + +2. **Monitor connection state** + - The SDK automatically attempts reconnection with appropriate backoff + - Listen for connection state changes to track recovery progress + - Publisher presence will automatically update when connection is restored + + +3. **Handle the unknown state gracefully** + - Display appropriate UI indicating temporary uncertainty about publisher locations + - Use the preserved `lastSeen` timestamps to show when publishers were last active + - Continue normal operation - tracking will resume automatically upon reconnection + + +## Automatic handling + +The Asset Tracking SDK automatically: +- Preserves publisher state information with `lastSeen` timestamps when connection is lost +- Attempts reconnection using the underlying Ably SDK's retry logic with exponential backoff +- Resumes normal tracking once connection is restored +- Transitions back from the UNKNOWN state to normal operation seamlessly + + +## Prevention + +- Implement proper network state monitoring in your application +- Handle app lifecycle events to manage tracking appropriately +- Use appropriate authentication token expiry times to minimize disconnections +- Consider implementing offline caching for critical tracking data + +## Related resources + +- [Asset Tracking Documentation](https://ably.com/docs/asset-tracking) +- [Connection State Management](https://ably.com/docs/realtime/connection) +- [Asset Tracking Android SDK](https://github.com/ably/ably-asset-tracking-android) +- Related error: [100004](https://help.ably.io/error/100004) - Subscriber has never been online + +## Need further help? + +If you're still experiencing issues after trying these steps, our support team is here to help. + +**Contact Ably Support**: https://ably.com/support + +When contacting support, please provide: +- Your account ID and app ID +- The full error message including error code 100005 +- Steps to reproduce the issue +- Any relevant code snippets (without sensitive credentials) +- The SDK and version you're using + +Our team will help you resolve this issue as quickly as possible. + + + + + + + + + + + + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/101000-space-name-missing.mdx b/src/pages/docs/platform/errors/codes/101000-space-name-missing.mdx new file mode 100644 index 0000000000..2d56debc15 --- /dev/null +++ b/src/pages/docs/platform/errors/codes/101000-space-name-missing.mdx @@ -0,0 +1,211 @@ + + + + + + + + +# Error 101000: Space name missing + +## What Happened + +The Ably Spaces SDK requires a valid space name but received an empty or invalid value when attempting to get or create a space. + +## Quick Reference + +| Error Code | HTTP Status | Category | Retryable | +|------------|-------------|----------|-----------| +| 101000 | 400 | Client Error (Validation) | No - requires fixing the space name parameter | + +## Quick Fix + +- Ensure you're passing a non-empty string as the space name +- Check that the name parameter isn't null, undefined, or an empty string +- Verify the parameter type is a string, not a number or object + +## Error Messages + +You'll see this message: +- "must have a non-empty name for the space" + +## Common Causes + +1. **Empty string passed** (40% of cases) + - Passing an empty string `""` to `spaces.get()` + - Accidentally clearing a variable before use + + +2. **Null or undefined value** (35% of cases) + - Variable not initialized before use + - Missing parameter in function call + - Async data not loaded yet + + +3. **Wrong parameter type** (25% of cases) + - Passing a number instead of a string + - Passing an object or array + - Type conversion issues + + +## Resolution Steps + +1. **Check your space name parameter** + ```javascript + // ❌ Wrong: These will trigger error 101000 + await spaces.get(""); // Empty string + await spaces.get(null); // Null value + await spaces.get(undefined); // Undefined + await spaces.get(123); // Number instead of string + await spaces.get({name: "room"}); // Object instead of string + + // ✅ Correct: Use a non-empty string + await spaces.get("my-space"); + await spaces.get("room-123"); + await spaces.get("chat-" + userId); + ``` + + +2. **Validate input before calling** + ```javascript + // Add validation before using the Spaces SDK + function getSpace(spaceName) { + if (typeof spaceName !== 'string' || spaceName.length === 0) { + throw new Error('Space name must be a non-empty string'); + } + return spaces.get(spaceName); + } + ``` + + +3. **Handle dynamic space names** + ```javascript + // When using dynamic names, ensure they're valid + const roomId = getRoomId(); // Could return null/undefined + + // ❌ Wrong: Direct use without validation + const space = await spaces.get(roomId); + + // ✅ Correct: Validate first + if (roomId && typeof roomId === 'string') { + const space = await spaces.get(roomId); + } else { + console.error('Invalid room ID:', roomId); + } + ``` + + +## Automatic Handling + +This is a validation error that occurs synchronously when you call `spaces.get()`. It will not be automatically retried as it indicates an issue with your code that must be fixed. + +## Prevention + +- **Always validate user input**: If space names come from user input, validate them before passing to the SDK +- **Use TypeScript**: TypeScript will catch type mismatches at compile time +- **Set default values**: Provide fallback values for optional parameters +- **Test edge cases**: Include tests for empty strings, null, and undefined values + +```javascript +// Example with proper validation +class SpaceManager { + constructor(spaces) { + this.spaces = spaces; + } + + async getOrCreateSpace(name) { + // Validate input + if (!name || typeof name !== 'string' || name.trim().length === 0) { + throw new Error(`Invalid space name: ${name}`); + } + + // Sanitize the name + const sanitizedName = name.trim(); + + try { + return await this.spaces.get(sanitizedName); + } catch (error) { + if (error.code === 101000) { + console.error('Space name validation failed:', error.message); + // Handle the error appropriately + } + throw error; + } + } +} +``` + + +## Related Resources + +- [Ably Spaces documentation](https://ably.com/docs/spaces) +- [Spaces SDK GitHub repository](https://github.com/ably/spaces) +- [Getting started with Spaces](https://ably.com/docs/spaces/get-started) + +## Need Further Help? + +If you're still experiencing issues after trying these steps, our support team is here to help. + +**Contact Ably Support**: https://ably.com/support + +When contacting support, please provide: +- Your account ID and app ID +- The full error message including error code 101000 +- Steps to reproduce the issue +- Any relevant code snippets (without sensitive credentials) +- The SDK and version you're using + +Our team will help you resolve this issue as quickly as possible. + + + + + + + + + + + + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/101001-not-entered-space.mdx b/src/pages/docs/platform/errors/codes/101001-not-entered-space.mdx new file mode 100644 index 0000000000..8f2314a84b --- /dev/null +++ b/src/pages/docs/platform/errors/codes/101001-not-entered-space.mdx @@ -0,0 +1,202 @@ + + + + + + + + +# Error 101001: Not entered space + +## What Happened + +You attempted to perform a space operation without first entering the space. + +## Quick Reference + +| Error Code | HTTP Status | Category | Retryable | +|------------|-------------|----------|-----------| +| 101001 | 400 | Client Error (Spaces) | No - requires entering space first | + +## Quick Fix + +- Call `space.enter()` with your profile data before performing operations +- Ensure the enter operation completes before calling other space methods +- Check that you're operating on the correct space instance + +## Error Messages + +You'll see this message: +- "must enter a space to perform this operation" + +## Common Causes + +1. **Not calling space.enter()** (90% of cases) + - Attempting operations immediately after getting a space reference + - Forgetting to enter the space in your initialization code + + +2. **Race conditions** (8% of cases) + - Calling space operations before `enter()` completes + - Not awaiting the enter operation + + +3. **Wrong space instance** (2% of cases) + - Operating on a different space than the one entered + - Creating multiple space instances accidentally + + +## Resolution Steps + +1. **Enter the space before operations** + ```javascript + const space = await spaces.get('mySpace'); + + // Enter with your profile data + await space.enter({ + username: 'Claire Lemons', + avatar: 'https://slides-internal.com/users/clemons.png', + }); + + // Now you can perform operations + await space.cursors.set({ position: { x: 50, y: 50 } }); + ``` + + +2. **Verify you've entered the space** + ```javascript + const self = await space.members.getSelf(); + if (!self) { + // Not entered - need to call space.enter() + await space.enter({ username: 'User Name' }); + } + ``` + + +3. **Handle the error gracefully** + ```javascript + try { + await space.cursors.set({ position: { x: 50, y: 50 } }); + } catch (error) { + if (error.code === 101001) { + // Guide user to enter space first + console.log('Please enter the space first using space.enter()'); + // Optionally auto-enter with default profile + await space.enter({ username: 'Anonymous' }); + // Retry operation + await space.cursors.set({ position: { x: 50, y: 50 } }); + } + } + ``` + + +## Automatic Handling + +The Spaces SDK does not automatically enter spaces. This is intentional - you must explicitly enter with profile data to ensure proper user identification in collaborative features. + + +## Code Examples + +### Proper Space Entry Pattern + +```javascript +// Recommended pattern +const space = await spaces.get('mySpace'); + +// Always enter before operations +await space.enter({ + username: 'User Name', + avatar: 'https://example.com/avatar.png', + // Additional profile data as needed +}); + +// Now safe to perform operations +await space.locations.set({ x: 100, y: 200 }); +await space.cursors.set({ position: { x: 50, y: 50 } }); +``` + + +### Operations That Require Entry + +The following operations will throw error 101001 if you haven't entered the space: +- **Lock operations**: `lock.acquire()`, `lock.release()` +- **Space membership**: `space.leave()` +- **Cursor management**: `cursors.set()` +- **Location tracking**: `locations.set()` + + +## Prevention + +- Always call `space.enter()` immediately after getting a space reference +- Use async/await to ensure enter completes before other operations +- Store the space instance to avoid creating duplicates +- Include proper error handling for space operations + + +## Related Resources + +- [Spaces documentation](https://ably.com/docs/spaces/space#enter) +- [Space.enter() API reference](https://ably.com/docs/spaces/space#enter) +- Related errors: [101000](https://help.ably.io/error/101000), [101002](https://help.ably.io/error/101002), [101003](https://help.ably.io/error/101003) + +## Need Further Help? + +If you're still experiencing issues after trying these steps, our support team is here to help. + +**Contact Ably Support**: https://ably.com/support + +When contacting support, please provide: +- Your account ID and app ID +- The full error message including error code 101001 +- Steps to reproduce the issue +- Any relevant code snippets (without sensitive credentials) +- The SDK and version you're using + +Our team will help you resolve this issue as quickly as possible. + + + + + + + + + + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/101002-lock-request-already-exists.mdx b/src/pages/docs/platform/errors/codes/101002-lock-request-already-exists.mdx new file mode 100644 index 0000000000..74d8ce88be --- /dev/null +++ b/src/pages/docs/platform/errors/codes/101002-lock-request-already-exists.mdx @@ -0,0 +1,190 @@ + + + + + + + + +# Error 101002: Lock request already exists + +## What Happened? + +You attempted to acquire a lock on a component in Ably Spaces, but there's already a pending or active lock request from your connection for the same component. + +## Quick Reference + +| Error Code | HTTP Status | Category | Retryable | +|------------|-------------|----------|-----------| +| 101002 | 400 | Client Error (Spaces - Locking) | No - requires handling existing lock first | + +## Quick Fix + +- Wait for your existing lock request to complete before making a new one +- Check the current lock status before attempting to acquire +- Release or cancel any existing locks before requesting a new one + +## Error Messages + +You'll see this exact message: +- "lock request already exists" + +## Common Causes + +1. **Multiple lock acquisition attempts** (90% of cases) + - Calling `acquire()` multiple times without waiting for the first to complete + - Attempting to acquire a lock that's already pending or locked by your connection + - Race conditions in application code triggering duplicate lock requests + + +2. **Missing lock state management** (10% of cases) + - Not tracking lock status in your application + - Ignoring lock state change events + - Not properly handling lock lifecycle + + +## Resolution Steps + +1. **Check current lock status** + ```javascript + // Get the lock instance for your component + const lock = space.locks.get('component-id'); + + // Check the current status + if (lock.status === 'pending' || lock.status === 'locked') { + // Wait for existing lock to resolve + console.log('Lock already exists, waiting...'); + } + ``` + + +2. **Handle existing lock appropriately** + - If `status === 'pending'`: Wait for the lock request to complete + - If `status === 'locked'`: Either use the existing lock or release it first + - If `status === 'unlocked'`: Safe to acquire a new lock + + +3. **Implement proper lock lifecycle management** + ```javascript + // React example with proper lock handling + const { status, member, acquire, release } = useLock('component-id'); + + const requestLock = async () => { + // Only acquire if not already locked or pending + if (status === 'unlocked') { + try { + const lock = await acquire(); + // Lock acquired successfully + } catch (error) { + if (error.code === 101002) { + console.log('Lock request already exists'); + // Handle appropriately + } + } + } + }; + ``` + + +4. **Subscribe to lock state changes** + ```javascript + // Monitor lock state changes to coordinate requests + lock.subscribe((update) => { + console.log(`Lock status changed to: ${update.status}`); + if (update.status === 'unlocked') { + // Now safe to acquire if needed + } + }); + ``` + + +## Automatic Handling + +The Ably Spaces SDK does not automatically retry lock acquisitions for this error. Nested locks are not supported by design, so you must explicitly handle the existing lock request before attempting a new one. + + +## Prevention + +- **Always check lock status** before calling `acquire()` +- **Implement state tracking** to know when you have pending or active locks +- **Use lock events** to coordinate multiple lock requests +- **Release locks promptly** when no longer needed to avoid conflicts +- **Avoid duplicate calls** to `acquire()` in event handlers or loops + + +## Related Resources + +- [Ably Spaces Locking Documentation](https://ably.com/docs/spaces/locking) +- [Component Locking States](https://ably.com/docs/spaces/locking#states) +- [Spaces React Hooks](https://ably.com/docs/spaces/react) +- Related errors: [101001](https://help.ably.io/error/101001) (Not entered space), [101003](https://help.ably.io/error/101003) (Lock is locked by another member) + +## Need Further Help? + +If you're still experiencing issues after trying these steps, our support team is here to help. + +**Contact Ably Support**: https://ably.com/support + +When contacting support, please provide: +- Your account ID and app ID +- The full error message including error code 101002 +- Steps to reproduce the issue +- Any relevant code snippets (without sensitive credentials) +- The SDK and version you're using + +Our team will help you resolve this issue as quickly as possible. + + + + + + + + + + + + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/101003-lock-is-locked.mdx b/src/pages/docs/platform/errors/codes/101003-lock-is-locked.mdx new file mode 100644 index 0000000000..cc88524c4d --- /dev/null +++ b/src/pages/docs/platform/errors/codes/101003-lock-is-locked.mdx @@ -0,0 +1,133 @@ + + + + + + + + +# Error 101003: Lock is locked + +## What Happened? +The component lock you requested is currently held by another user, and your request did not take priority. + +## Quick Reference +| Error Code | HTTP Status | Category | Retryable | +|------------|-------------|----------|-----------| +| 101003 | 400 | Locking/Conflict (Spaces) | Yes - lock will become available | + +## Quick Fix +- This is normal behavior when multiple users try to lock the same component +- Subscribe to lock update events to know when the lock becomes available +- Implement retry logic with appropriate backoff + +## Error Messages +You'll see this in the lock response: +- "lock is currently locked" + +## Common Causes + +1. **Concurrent lock attempts** (Most common) + - Multiple users trying to edit the same component simultaneously + - Normal behavior in collaborative applications + + +2. **Network timing** + - Lock requests arriving out of order + - Presence system delays affecting lock state synchronization + + +## Resolution Steps + +1. **Handle as expected behavior** + - This is not an error but normal lock contention + - Design your UI to gracefully handle locked components + + +2. **Subscribe to lock updates** + - Monitor when the lock becomes available + - Automatically retry when the lock is released + + +3. **Implement visual feedback** + - Show who currently holds the lock + - Display queue position if applicable + - Notify users when locks become available + + +## Automatic Handling +The Spaces SDK does not automatically retry lock acquisition. Your application should implement appropriate retry logic based on your use case. + + +## Prevention +- Consider using optimistic UI updates where appropriate +- Design your collaborative features to minimize lock contention +- Implement clear visual indicators of component availability + + +## Related Resources +- [Ably Spaces Component Locking documentation](https://ably.com/docs/spaces/locking) +- [Ably Spaces SDK documentation](https://ably.com/docs/spaces) +- Related errors: None (this is a Spaces-specific lock contention indicator) + + +## Need Further Help? + +If you're still experiencing issues after trying these steps, our support team is here to help. + +**Contact Ably Support**: https://ably.com/support + +When contacting support, please provide: +- Your account ID and app ID +- The full error message including error code 101003 +- Steps to reproduce the issue +- Any relevant code snippets (without sensitive credentials) +- The SDK and version you're using + +Our team will help you resolve this issue as quickly as possible. + + + + + + + + + + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/101004-lock-invalidated.mdx b/src/pages/docs/platform/errors/codes/101004-lock-invalidated.mdx new file mode 100644 index 0000000000..85c8c938f3 --- /dev/null +++ b/src/pages/docs/platform/errors/codes/101004-lock-invalidated.mdx @@ -0,0 +1,222 @@ + + + + + + + + +# Error 101004: Lock invalidated + +## What Happened + +Your lock request on a Spaces component was invalidated by another member's lock request that had higher priority. + +## Quick Reference + +| Error Code | HTTP Status | Category | Retryable | +|------------|-------------|----------|-----------| +| 101004 | 400 | Locking/Conflict Resolution (Spaces) | Yes - can retry after invalidation | + +## Quick Fix + +- Your lock was invalidated by a concurrent request with higher priority (earlier timestamp or lower connection ID) +- Subscribe to lock update events to detect when your lock is invalidated +- Implement retry logic or notify the user that another member now holds the lock + +## Error Messages + +You'll see this in the lock's `reason` property when it transitions to `unlocked`: +- "lock was invalidated by a concurrent lock request which now holds the lock" +- "Lock invalidated" + +## Common Causes + +1. **Concurrent lock requests** (90% of cases) + - Multiple members attempting to lock the same component simultaneously + - The member with the earlier timestamp gets priority + + +2. **Network latency differences** (8% of cases) + - Members with better network conditions may submit requests with earlier timestamps + - Slight timing differences can affect lock priority + +3. **Component lifecycle issues** (2% of cases) + - React components not properly cleaning up lock subscriptions + - Lock events firing after component unmounting + + +## Resolution Steps + +1. **Subscribe to lock update events** + ```javascript + space.locks.subscribe('update', (lock) => { + if (lock.reason?.code === 101004) { + // Your lock was invalidated + handleLockInvalidation(lock); + } + }); + ``` + + +2. **Implement graceful handling** + - Notify the user that another member has taken control + - Update your UI to reflect the locked state + - Consider implementing a queue or retry mechanism + +3. **For React applications: Ensure proper cleanup** + ```javascript + useEffect(() => { + const subscription = space.locks.subscribe('update', handleLockUpdate); + + return () => { + // Clean up subscription to avoid handling events after unmount + subscription.unsubscribe(); + }; + }, []); + ``` + + +4. **Understanding lock priority** + - Earlier timestamps always win + - When timestamps are identical, lower connection IDs win + - This ensures deterministic conflict resolution across all clients + + +## Automatic Handling + +Unlike thrown exceptions, error 101004 is assigned to the lock's `reason` property when invalidated. This allows your application to: +- Continue running without exception handling +- React to lock state changes through event subscriptions +- Handle invalidation gracefully without disrupting user experience + + +## Code Examples + +### Complete Lock Management with Invalidation Handling + +```javascript +// Initialize Spaces +const space = await spaces.get('collaborative-doc'); + +// Request a lock with invalidation handling +async function acquireLockWithHandling(componentId) { + try { + // Subscribe to lock updates before acquiring + const subscription = space.locks.subscribe('update', (lock) => { + if (lock.id === componentId && lock.reason?.code === 101004) { + // Lock was invalidated + console.log('Lock invalidated by another member'); + updateUIForLockedState(); + + // Optional: Retry after delay + setTimeout(() => retryLockAcquisition(componentId), 2000); + } + }); + + // Attempt to acquire lock + const lock = await space.locks.acquire(componentId); + console.log('Lock acquired successfully'); + + return { lock, subscription }; + } catch (error) { + if (error.code === 101002) { + // Lock already held by another member + console.log('Component already locked'); + } + throw error; + } +} + +// Clean up when done +function releaseLock(lock, subscription) { + subscription.unsubscribe(); + return lock.release(); +} +``` + + +## Prevention + +- Implement visual indicators showing when components are locked +- Use optimistic UI updates with rollback capabilities +- Consider implementing a queue system for lock requests +- In React apps, always clean up lock subscriptions in useEffect cleanup functions + +## Related Resources + +- [Spaces Locking Documentation](https://ably.com/docs/spaces/locking) +- [Spaces React Hooks](https://ably.com/docs/spaces/react) +- [Component Locking Guide](https://ably.com/docs/spaces/locking#handling-lock-conflicts) +- Related errors: [101002](https://help.ably.io/error/101002) (lock already held), [101003](https://help.ably.io/error/101003) (lock released) + +## Need Further Help? + +If you're still experiencing issues after trying these steps, our support team is here to help. + +**Contact Ably Support**: https://ably.com/support + +When contacting support, please provide: +- Your account ID and app ID +- The full error message including error code 101004 +- Steps to reproduce the issue +- Any relevant code snippets (without sensitive credentials) +- The SDK and version you're using + +Our team will help you resolve this issue as quickly as possible. + + + + + + + + + + + + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/10200-unrecognized-error.mdx b/src/pages/docs/platform/errors/codes/10200-unrecognized-error.mdx new file mode 100644 index 0000000000..8f84acdfa4 --- /dev/null +++ b/src/pages/docs/platform/errors/codes/10200-unrecognized-error.mdx @@ -0,0 +1,118 @@ + + + + + + + + +# Error 10200: Unrecognized error code + +## What Happened + +An unrecognized error code was encountered. This error code is not currently active in Ably's systems. + +## Quick Reference + +| Error Code | HTTP Status | Category | Retryable | +|------------|-------------|----------|-----------| +| 10200 | N/A | Unknown | No - unrecognized error | + +## Quick Fix + +- Verify you're using the latest SDK version +- Check if you meant to reference error code 102000 (Chat room validation) +- Contact Ably support for assistance + +## Error Messages + +This error code has no associated error messages in Ably's current systems. + +## Common Causes + +This error code may appear due to: + +1. **Parsing or logging issues** + - Error extraction tools misrepresenting other error codes + - Logging systems truncating longer error codes + +2. **Possible confusion with error 102000** + - Chat room name validation errors + - If working with Ably Chat, check room name format + +## Resolution Steps + +1. **Verify the actual error code** + - Check your logs for the complete error code + - Look for 6-digit error codes that may have been truncated + +2. **If using Ably Chat** + - You may be encountering error 102000 (room name validation) + - Ensure room names don't start with ':', ',', '[' or spaces + - Ensure room names don't contain '::$' + +3. **Update your SDK** + - Ensure you're using the latest version of your Ably SDK + - Check the [Ably SDK downloads page](https://ably.com/download) for updates + +## Automatic Handling + +This error code is not recognized by Ably SDKs and will not be automatically handled. + +## Need Further Help? + +This error code has limited documentation available. If you encounter this error, please contact Ably support at https://ably.com/support with: +- The full error message +- What action triggered the error +- Your account ID and app ID +- The exact error code you're seeing (including all digits) +- The SDK and version you're using + +Our support team will help you resolve this issue as quickly as possible. + + + + + + + + + + + + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/102100-room-discontinuity.mdx b/src/pages/docs/platform/errors/codes/102100-room-discontinuity.mdx new file mode 100644 index 0000000000..067a30c74f --- /dev/null +++ b/src/pages/docs/platform/errors/codes/102100-room-discontinuity.mdx @@ -0,0 +1,215 @@ + + + + + + + + +# Error 102100: Room discontinuity + +## What Happened + +Your chat room has experienced a discontinuity that requires the application to re-synchronize its state with the server. + +## Quick Reference + +| Error Code | HTTP Status | Category | Retryable | +|------------|-------------|----------|-----------| +| 102100 | 400/500 | Room Lifecycle (Chat SDK) | Yes - requires room re-attachment | + +## Quick Fix + +- The Chat SDK automatically emits discontinuity events to your application +- Re-attach the room to restore connectivity +- Synchronize missed messages using the history API + +## Error Messages + +You may see one of these messages: +- "discontinuity detected" +- "Discontinuity detected, [original error message]" +- "The room has experienced a discontinuity" + +## Common Causes + +1. **Extended disconnection** (most common) + - Network interruption lasting beyond 2 minutes + - Exceeds automatic recovery window + - Channel state cannot be preserved + + +2. **Server-side connection termination** + - Load balancing operations + - Server maintenance or updates + - Connection shedding for resource management + + +3. **Channel state loss** + - Channel re-attaches without the `resumed` flag + - Previous message continuity cannot be guaranteed + - Requires full state resynchronization + + +## Resolution Steps + +1. **Listen for discontinuity events** + ```javascript + // JavaScript/TypeScript + room.on('discontinuity', (error) => { + // Handle error code 102100 + handleDiscontinuity(); + }); + ``` + + +2. **Re-attach the affected room** + - Call the room's attach method + - Wait for successful attachment + - This restores the connection to all room features + + +3. **Synchronize room state** + - Retrieve missed messages using `getPreviousMessages()` or history API + - Update your UI with the latest message state + - Re-synchronize presence information if needed + + +4. **Notify users of recovery** + - Display a reconnection indicator during recovery + - Clear the indicator once synchronization is complete + - Consider queuing outgoing messages during recovery + + +## Automatic Handling + +The Ably Chat SDK automatically: +- Detects discontinuities when channels re-attach without preserving state +- Emits discontinuity events to your application +- Handles transient disconnections (under 2 minutes) without emitting this error +- Preserves message history that can be retrieved after recovery + + +## Code Examples + +### JavaScript/TypeScript +```javascript +room.on('discontinuity', async (error) => { + if (error.code === 102100) { + // Show reconnecting indicator + showReconnectingUI(); + + // Re-attach the room + await room.attach(); + + // Sync missed messages + const history = await room.messages.getPreviousMessages({ limit: 100 }); + updateMessageList(history); + + // Clear reconnecting indicator + hideReconnectingUI(); + } +}); +``` + + +### Kotlin/Android +```kotlin +room.onDiscontinuity { error -> + if (error.code == 102100) { + // Handle discontinuity + room.attach() + syncLatestMessages() + } +} +``` + + +### Swift/iOS +```swift +room.onDiscontinuity { event in + if event.error.code == 102100 { + // Recover room state + try await room.attach() + try await synchronizeRoomState() + } +} +``` + + +## Prevention + +While discontinuities cannot be completely prevented due to network conditions, you can minimize their impact: + +- Implement robust discontinuity event handlers from the start +- Design your UI to gracefully handle temporary disconnections +- Cache recent messages locally for immediate display during recovery +- Use visual indicators to keep users informed of connection status + + +## Related Resources + +- [Ably Chat SDK documentation](https://ably.com/docs/products/chat) +- [Connection state management](https://ably.com/docs/connect/states) +- [Message history and recovery](https://ably.com/docs/storage-history/history) +- Related errors: [102101](./102101-room-failed.mdx) (Room failed), [102106](./102106-room-released.mdx) (Room released) + +## Need Further Help? + +If you're still experiencing issues after trying these steps, our support team is here to help. + +**Contact Ably Support**: https://ably.com/support + +When contacting support, please provide: +- Your account ID and app ID +- The full error message including error code 102100 +- Steps to reproduce the issue +- Any relevant code snippets (without sensitive credentials) +- The SDK and version you're using + +Our team will help you resolve this issue as quickly as possible. + + + + + + + + + + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/102101-room-in-failed-state.mdx b/src/pages/docs/platform/errors/codes/102101-room-in-failed-state.mdx new file mode 100644 index 0000000000..5fd9489299 --- /dev/null +++ b/src/pages/docs/platform/errors/codes/102101-room-in-failed-state.mdx @@ -0,0 +1,175 @@ + + + + + + + + +# Error 102101: Room in failed state + +## What Happened + +The Chat room you're trying to use has entered a failed state and cannot perform any operations. + +## Quick Reference + +| Error Code | HTTP Status | Category | Retryable | +|------------|-------------|----------|-----------| +| 102101 | 400 | Chat Room Lifecycle | No - room must be released and recreated | + +## Quick Fix + +- Release the failed room using `room.release()` +- Create a new room instance with `chat.rooms.get()` +- Monitor room status to detect failures early + +## Error Messages + +You may see one of these messages: +- "unable to perform operation; room is in failed state" +- "cannot detach room, room is in failed state" +- "Cannot perform operation because the room is in a failed state" + +## Common Causes + +1. **Underlying channel failures** (90% of cases) + - Network connectivity issues causing channel disconnections + - Authentication failures on room channels + - Server-side errors affecting room channels + + +2. **Irrecoverable room errors** (10% of cases) + - Room entered terminal failed state after multiple retry attempts + - Critical errors during room initialization or attachment + + +## Resolution Steps + +1. **Check the room status** + ```javascript + if (room.status === RoomStatus.Failed) { + console.log('Room has failed and must be recreated'); + } + ``` + + +2. **Release the failed room** + ```javascript + await room.release(); + ``` + + +3. **Create a new room instance** + ```javascript + const newRoom = await chat.rooms.get('room-id', { + // Your room options + }); + await newRoom.attach(); + ``` + + +4. **Monitor room status to prevent future failures** + ```javascript + room.on('status', (status) => { + if (status === RoomStatus.Failed) { + // Handle room failure + handleRoomFailure(); + } + }); + ``` + + +## Automatic Handling + +Ably Chat SDKs do not automatically recover from room failed states. When a room enters the failed state: +- All operations on the room are blocked +- The room remains in failed state permanently +- You must manually release and recreate the room + + +## Prevention + +- **Monitor connection health**: Track underlying Ably connection status +- **Handle channel errors gracefully**: Respond to channel-level errors before they cause room failure +- **Implement room status monitoring**: React to room status changes proactively +- **Use appropriate error handling**: Catch and handle room lifecycle errors properly + + +## Related Resources + +- [Ably Chat documentation](https://ably.com/docs/chat) +- [Room lifecycle management](https://ably.com/docs/chat/rooms) +- [Connection state handling](https://ably.com/docs/connect) +- Related errors: Room lifecycle errors in the 102xxx range + +## Need Further Help? + +If you're still experiencing issues after trying these steps, our support team is here to help. + +**Contact Ably Support**: https://ably.com/support + +When contacting support, please provide: +- Your account ID and app ID +- The full error message including error code 102101 +- Steps to reproduce the issue +- Any relevant code snippets (without sensitive credentials) +- The SDK and version you're using + +Our team will help you resolve this issue as quickly as possible. + + + + + + + + + + + + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/102102-room-is-releasing.mdx b/src/pages/docs/platform/errors/codes/102102-room-is-releasing.mdx new file mode 100644 index 0000000000..0bd7682f63 --- /dev/null +++ b/src/pages/docs/platform/errors/codes/102102-room-is-releasing.mdx @@ -0,0 +1,192 @@ + + + + + + + + +# Error 102102: Room is releasing + +## What Happened? + +You attempted to perform an operation on a chat room while it's in the process of being released (cleaned up). + +## Quick Reference + +| Error Code | HTTP Status | Category | Retryable | +|------------|-------------|----------|-----------| +| 102102 | 400 | Client Error (Chat SDK) | No - must wait for release to complete | + +## Quick Fix + +- Wait for the room release to complete before attempting operations +- Create a new room instance instead of operating on a releasing room +- Check room status before performing operations + +## Error Messages + +You may see one of these messages: +- "cannot [operation] room, room is currently releasing" (JavaScript) +- "Cannot perform operation because the room is in a releasing state" (Swift) + +The `[operation]` placeholder shows the specific action you attempted (attach, detach, presence, etc.). + +## Common Causes + +1. **Rapid room operations** (80% of cases) + - Attempting to attach immediately after initiating release + - Trying to use a room that's being cleaned up + - Not waiting for release completion + + +2. **Improper state management** (15% of cases) + - Application not tracking room lifecycle correctly + - Missing status checks before operations + - Concurrent operations on the same room + + +3. **Race conditions** (5% of cases) + - Multiple parts of application accessing room during release + - Asynchronous operations overlapping with release + + +## Resolution Steps + +1. **Check room status before operations** + + ```javascript + // ✅ Correct: Check status first + if (room.status !== 'releasing' && room.status !== 'released') { + await room.attach(); + } + + // ❌ Wrong: Operating without checking + await room.attach(); // May throw 102102 + ``` + + +2. **Wait for release to complete** + + Listen for status changes and wait for the room to be fully released: + ```javascript + room.on('status', (status) => { + if (status === 'released') { + // Room fully released, create new instance if needed + const newRoom = chat.rooms.get(roomId); + } + }); + ``` + + +3. **Create a new room instance** + + Instead of waiting, immediately create a fresh room instance: + ```javascript + // Release old room + await oldRoom.release(); + + // Create new instance with same ID + const newRoom = chat.rooms.get(roomId); + await newRoom.attach(); + ``` + + +4. **Implement proper lifecycle management** + + Ensure graceful shutdown sequence: + - Complete all pending operations + - Initiate release + - Wait for release completion + - Only then create new instances if needed + +## Automatic Handling + +The Ably Chat SDKs enforce this validation to prevent race conditions and ensure data consistency. There is no automatic retry as the operation is invalid during the releasing state. + + +## Prevention + +- Always check room status before performing operations +- Implement proper state tracking in your application +- Use event listeners to monitor room lifecycle changes +- Avoid rapid create/release cycles on the same room + + +## Related Resources + +- [Ably Chat Documentation](https://ably.com/docs/chat) +- [Chat Rooms Guide](https://ably.com/docs/chat/rooms) +- Related errors: [102101](./102101-room-is-released.mdx) (Room is released), [102103](./102103-room-is-failed.mdx) (Room is failed) + + +## Need Further Help? + +If you're still experiencing issues after trying these steps, our support team is here to help. + +**Contact Ably Support**: https://ably.com/support + +When contacting support, please provide: +- Your account ID and app ID +- The full error message including error code 102102 +- Steps to reproduce the issue +- Any relevant code snippets (without sensitive credentials) +- The SDK and version you're using + +Our team will help you resolve this issue as quickly as possible. + + + + + + + + + + + + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/102103-room-is-released.mdx b/src/pages/docs/platform/errors/codes/102103-room-is-released.mdx new file mode 100644 index 0000000000..225b520505 --- /dev/null +++ b/src/pages/docs/platform/errors/codes/102103-room-is-released.mdx @@ -0,0 +1,207 @@ + + + + + + + + +# Error 102103: Room is released + +## What Happened + +You attempted to perform an operation on a Chat room that has already been released and deallocated. + +## Quick Reference + +| Error Code | HTTP Status | Category | Retryable | +|------------|-------------|----------|-----------| +| 102103 | 400 | Client Error (Chat SDK) | No - requires new room instance | + +## Quick Fix + +- Get a new room instance using `rooms.get(roomId)` +- Update your references to point to the new room +- Avoid caching room instances that might outlive their lifecycle + +## Error Messages + +You may see one of these messages: +- "cannot {operation} room, room is released" (JavaScript) +- "unable to attach room; room is released" (Kotlin/Android) +- "unable to detach room; room is released" (Kotlin/Android) +- "Cannot perform operation because the room is in a released state" (Swift/iOS) + +## Common Causes + +1. **Reusing released room references** (80% of cases) + - Attempting to use a room after calling `release()` + - Holding onto room references after the room lifecycle ends + - Not updating references after room recreation + + +2. **Race conditions** (15% of cases) + - Operations attempted during or after room release + - Asynchronous code not properly synchronized with room lifecycle + - Event handlers firing after room release + + +3. **Improper lifecycle management** (5% of cases) + - Not handling room lifecycle events properly + - Missing cleanup in component unmount/destroy handlers + + +## Resolution Steps + +1. **Get a new room instance** + ```javascript + // JavaScript/TypeScript + const newRoom = await chat.rooms.get(roomId); + + // Kotlin/Android + val newRoom = chat.rooms.get(roomId) + + // Swift/iOS + let newRoom = try await chat.rooms.get(roomId: roomId) + ``` + + +2. **Update all references** + - Replace any stored references with the new room instance + - Update event listeners to use the new room + - Ensure UI components reference the updated room + +3. **Implement proper lifecycle management** + ```javascript + // Example: React component with proper cleanup + useEffect(() => { + let room; + + async function setupRoom() { + room = await chat.rooms.get(roomId); + await room.attach(); + // Setup subscriptions + } + + setupRoom(); + + return () => { + // Cleanup on unmount + if (room) { + room.release(); + } + }; + }, [roomId]); + ``` + + +4. **Handle room lifecycle states** + - Monitor room status before operations + - Implement appropriate error handling + - Consider implementing reconnection logic for your use case + +## Automatic Handling + +The Chat SDK does not automatically recover from this error. Once a room is released, it cannot be reused. You must explicitly obtain a new room instance. + + +## Prevention + +- **Never cache room instances** beyond their intended lifecycle +- **Always check room status** before performing operations +- **Implement proper cleanup** in your application lifecycle hooks +- **Use room lifecycle events** to track state changes +- **Avoid long-lived references** to room objects + + +## Understanding Room Lifecycle + +The Chat SDK implements a room lifecycle state machine: +- **Attached**: Room is connected and operational +- **Detaching**: Room is disconnecting +- **Detached**: Room is disconnected but not released +- **Releasing**: Room is being deallocated +- **Released**: Room is deallocated (triggers error 102103) + +Once a room reaches the Released state, it cannot be reused. This is a terminal state designed to prevent use-after-free type bugs. + + +## Related Resources + +- [Ably Chat documentation](https://ably.com/docs/chat) +- [Chat SDK room lifecycle](https://ably.com/docs/chat/rooms) +- Related errors: + - [102100](./102100-room-discontinuity.mdx) - Room discontinuity + - [102101](./102101-room-in-failed-state.mdx) - Room in failed state + - [102102](./102102-room-is-releasing.mdx) - Room is releasing + +## Need Further Help? + +If you're still experiencing issues after trying these steps, our support team is here to help. + +**Contact Ably Support**: https://ably.com/support + +When contacting support, please provide: +- Your account ID and app ID +- The full error message including error code 102103 +- Steps to reproduce the issue +- Any relevant code snippets (without sensitive credentials) +- The SDK and version you're using + +Our team will help you resolve this issue as quickly as possible. + + + + + + + + + + + + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/102106-room-released-before-operation-completed.mdx b/src/pages/docs/platform/errors/codes/102106-room-released-before-operation-completed.mdx new file mode 100644 index 0000000000..994c14657b --- /dev/null +++ b/src/pages/docs/platform/errors/codes/102106-room-released-before-operation-completed.mdx @@ -0,0 +1,215 @@ + + + + + + + + +# Error 102106: Room released before operation completed + +## What Happened + +A Chat room was released while a `rooms.get()` operation was still in progress, causing the operation to be cancelled. + +## Quick Reference + +| Error Code | HTTP Status | Category | Retryable | +|------------|-------------|----------|-----------| +| 102106 | 400 | Client Error (Chat SDK) | Yes - after verifying application state | + +## Quick Fix + +- Check your application's room lifecycle management +- Ensure `rooms.release()` isn't called while `rooms.get()` is pending +- Retry the `rooms.get()` operation if the room is still needed + +## Error Messages + +You'll see this message: +- "room released before get operation could complete" + +## Common Causes + +1. **Race condition in component lifecycle** (70% of cases) + - Component unmounting while room initialization is in progress + - User navigation triggering cleanup during room loading + - Multiple components managing the same room simultaneously + + +2. **Application shutdown during initialization** (20% of cases) + - App cleanup running while rooms are being fetched + - Browser/app closing during async operations + + +3. **Improper async operation handling** (10% of cases) + - Not awaiting room operations before cleanup + - Missing coordination between room get and release calls + + +## Resolution Steps + +1. **Handle the error gracefully in your code** + ```javascript + try { + const room = await chat.rooms.get('my-room-id'); + // Use the room + } catch (error) { + if (error.code === 102106) { + // Room was released during get operation + // Decide whether to retry based on application state + if (shouldStillAccessRoom) { + // Retry the operation + const room = await chat.rooms.get('my-room-id'); + } else { + // Handle gracefully - room is no longer needed + console.log('Room access cancelled'); + } + } + } + ``` + + +2. **Improve your room lifecycle management** + - Implement a centralized room manager to coordinate access + - Use reference counting for shared room instances + - Ensure cleanup operations wait for initialization to complete + + +3. **Fix component lifecycle issues (React example)** + ```javascript + useEffect(() => { + let cancelled = false; + + async function setupRoom() { + try { + const room = await chat.rooms.get('my-room-id'); + if (!cancelled) { + // Only use room if component is still mounted + setRoom(room); + } + } catch (error) { + if (error.code === 102106 && !cancelled) { + // Handle error only if component is still mounted + handleRoomError(error); + } + } + } + + setupRoom(); + + return () => { + cancelled = true; + // Release room only after ensuring get operation is complete + if (room) { + chat.rooms.release('my-room-id'); + } + }; + }, []); + ``` + + +4. **Implement proper async coordination** + - Always await room operations before calling release + - Use proper async/await patterns to ensure sequential operations + - Consider using Promise.allSettled() for multiple room operations + + +## Automatic Handling + +The Chat SDKs automatically: +- Cancel pending `rooms.get()` operations when `rooms.release()` is called +- Clean up resources to prevent memory leaks +- Log debug information about the cancellation + +This error is part of the defensive programming built into the SDK to ensure proper resource cleanup. + + +## Prevention + +- **Coordinate room operations**: Avoid calling `rooms.release()` while `rooms.get()` may be in progress +- **Use proper lifecycle management**: Implement cleanup in the correct component lifecycle phase +- **Handle async operations properly**: Always await or properly handle promises +- **Implement room reference counting**: Track active users of a room before releasing + + +## Related Resources + +- [Ably Chat documentation](https://ably.com/docs/chat) +- [Chat Rooms API reference](https://ably.com/docs/chat/rooms) +- [Chat SDK Specification CHA-RC1g4](https://github.com/ably/specification/tree/main/textile/chat#CHA-RC1g4) +- Related errors: None currently - this is a Chat-specific error + +## Need Further Help? + +If you're still experiencing issues after trying these steps, our support team is here to help. + +**Contact Ably Support**: https://ably.com/support + +When contacting support, please provide: +- Your account ID and app ID +- The full error message including error code 102106 +- Steps to reproduce the issue +- Any relevant code snippets (without sensitive credentials) +- The SDK and version you're using + +Our team will help you resolve this issue as quickly as possible. + + + + + + + + + + + + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/102107-room-invalid-state.mdx b/src/pages/docs/platform/errors/codes/102107-room-invalid-state.mdx new file mode 100644 index 0000000000..ca40769a5c --- /dev/null +++ b/src/pages/docs/platform/errors/codes/102107-room-invalid-state.mdx @@ -0,0 +1,195 @@ + + + + + + + + +# Error 102107: Room invalid state + +## What Happened + +The Chat SDK cannot perform the requested operation because the chat room is not in the correct state. + +## Quick Reference + +| Error Code | HTTP Status | Category | Retryable | +|------------|-------------|----------|-----------| +| 102107 | 400/500 | Client Error (Chat SDK) | No - requires room attachment | + +## Quick Fix + +- Attach the room before performing presence operations +- Wait for room to reach ATTACHED state +- Check room status before operations + +## Error Messages + +You may see one of these messages: +- "Can't perform operation; the room '{roomName}' is in an invalid state: {roomStatus}" +- "The room operation failed because the room was in an invalid state." +- "To perform this {feature} operation, you must first attach the room." + +The `{roomName}` shows the specific room identifier, `{roomStatus}` shows the current room state, and `{feature}` indicates the operation type (e.g., presence). + +## Common Causes + +1. **Room not attached** (80% of cases) + + - Attempting presence operations before attaching room + - Room in INITIALIZED, SUSPENDED, or FAILED state + - Missing room.attach() call + +2. **Room state transition failure** (15% of cases) + + - Room was ATTACHING but transitioned to non-ATTACHED state + - Network interruption during attachment + - Authentication issues during attachment + +3. **Room in terminal state** (5% of cases) + + - Room is FAILED or SUSPENDED + - Previous error left room in unusable state + - Room requires reinitialization + +## Resolution Steps + +1. **Attach the room before operations** + + ```kotlin + // Kotlin/Android + val room = chatClient.rooms.get(roomId) + room.attach() + // Now safe to perform presence operations + room.presence.enter() + ``` + + ```swift + // Swift/iOS + let room = chatClient.rooms.get(roomID: roomId) + try await room.attach() + // Now safe to perform presence operations + try await room.presence.enter() + ``` + +2. **Check room status before operations** + + ```kotlin + // Kotlin/Android + if (room.status == RoomStatus.ATTACHED) { + // Safe to perform operations + room.presence.update(userData) + } else { + // Attach first + room.attach() + } + ``` + +3. **Handle state transition failures** + + ```swift + // Swift/iOS + do { + try await room.presence.enter() + } catch { + if let ablyError = error as? ARTErrorInfo, + ablyError.code == 102107 { + // Attach room and retry + try await room.attach() + try await room.presence.enter() + } + } + ``` + +4. **Monitor room status changes** + + Subscribe to room status changes to ensure operations only occur when room is attached. This prevents the error from occurring in the first place. + +## Automatic Handling + +The Chat SDK does not automatically retry this error. You must explicitly attach the room and retry the operation. + +## Prevention + +- Always call `room.attach()` before any presence operations +- Implement room status listeners to track state changes +- Use try-catch blocks around presence operations +- Wait for room attachment to complete before proceeding + +## Related Resources + +- [Ably Chat documentation](https://ably.com/docs/chat) +- [Chat SDK room lifecycle](https://ably.com/docs/chat/rooms) +- [Presence in Chat](https://ably.com/docs/chat/rooms#presence) +- Related errors: [80000](./80000-connection-failed.md), [91001](./91001-channel-operation-failed.md) + +## Need Further Help? + +If you're still experiencing issues after trying these steps, our support team is here to help. + +**Contact Ably Support**: https://ably.com/support + +When contacting support, please provide: +- Your account ID and app ID +- The full error message including error code 102107 +- Steps to reproduce the issue +- Any relevant code snippets (without sensitive credentials) +- The SDK and version you're using + +Our team will help you resolve this issue as quickly as possible. + + + + + + + + + + + + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/20000-informational-status.mdx b/src/pages/docs/platform/errors/codes/20000-informational-status.mdx new file mode 100644 index 0000000000..d4ba325c48 --- /dev/null +++ b/src/pages/docs/platform/errors/codes/20000-informational-status.mdx @@ -0,0 +1,182 @@ + + + + + + + + +# Error 20000: Informational status + +## What Happened + +The Ably protocol requires an ErrorInfo object for certain operations, even when nothing is wrong—this is that informational status. + +## Quick Reference + +| Error Code | HTTP Status | Category | Retryable | +|------------|-------------|----------|-----------| +| 20000 | 200/204 | Protocol Information | N/A - not an actual error | + +## Quick Fix + +- **No action required** - This is normal protocol behavior +- Check the message text to understand what operation completed +- Continue normal operations + +## Error Messages + +You may see one of these informational messages: +- "Transport superseded" (most common - 60% of cases) +- "Transport superseded as active transport" +- "Connection superseded" +- "Client no longer needed, resource being disposed" +- "Coordinator idle (no existing coordinator and create-on-request disabled)" +- "Declining token as not active" +- "Unable to hand token off to successor" +- "Transient attachment detaching" + +## Common Causes + +This isn't an error but appears in these normal scenarios: + +1. **Connection upgrades** (60% of occurrences) + - WebSocket connection replacing an older connection + - Multiple browser tabs or iframes connecting to same channel + - Transport protocol switching (WebSocket to HTTP or vice versa) + + +2. **Resource cleanup** (20% of occurrences) + - Unused connections being closed + - Idle coordinators shutting down + - Global resources being disposed + + +3. **Channel management** (20% of occurrences) + - Channel relocations on backend + - Inactive channels declining lifecycle tokens + - Channel attachment state changes + + +## Why You're Seeing This + +Error 20000 appears in logs during normal Ably operations. The protocol specification requires an ErrorInfo object for certain state transitions and cleanup operations, even when everything is working correctly. Think of it as an "FYI" status rather than an error. + + +Common situations where you'll see this: +- Opening your app in multiple browser tabs +- Recovering from temporary network disconnections +- Normal connection lifecycle during long-running sessions +- Backend load balancing operations + + +## Resolution Steps + +Since this isn't an actual error, no resolution is needed. However, if you're concerned: + +1. **Verify your app is working normally** + - Check that messages are being sent and received + - Confirm presence updates are working + - Ensure no actual connectivity issues exist + +2. **Check the specific message text** + - "Transport superseded" means a newer connection replaced an older one (normal) + - "Resource being disposed" means cleanup of unused resources (normal) + - "Coordinator idle" means the coordinator entered standby mode (normal) + + +3. **Monitor for actual issues** + - Look for error codes in the 40xxx, 50xxx, or 80xxx ranges + - Check for connection state changes to `failed` or `suspended` + - Watch for message delivery failures + +## Automatic Handling + +Ably SDKs handle all scenarios that generate error 20000 automatically. The SDK: +- Manages connection upgrades transparently +- Cleans up resources as needed +- Handles channel relocations seamlessly +- Maintains message delivery throughout these operations + + +## Prevention + +You cannot and should not try to prevent error 20000—it's a normal part of Ably's operation. If you want to reduce log noise: + +- Consider filtering out error 20000 from your error monitoring +- Log it at INFO or DEBUG level rather than ERROR +- Focus monitoring on actual error codes that require attention + +## Related Resources + +- [Connection state management](https://ably.com/docs/realtime/connection) +- [Understanding Ably's protocol](https://ably.com/docs/client-lib-development-guide/protocol) +- [Channel lifecycle](https://ably.com/docs/channels) + +## Need Further Help? + +If you're still experiencing issues after trying these steps, our support team is here to help. + +**Contact Ably Support**: https://ably.com/support + +When contacting support, please provide: +- Your account ID and app ID +- The full error message including error code 20000 +- Steps to reproduce the issue +- Any relevant code snippets (without sensitive credentials) +- The SDK and version you're using + +Our team will help you resolve this issue as quickly as possible. + + + + + + + + + + + + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/40000-bad-request.mdx b/src/pages/docs/platform/errors/codes/40000-bad-request.mdx new file mode 100644 index 0000000000..8457ed9cbb --- /dev/null +++ b/src/pages/docs/platform/errors/codes/40000-bad-request.mdx @@ -0,0 +1,271 @@ + + + + + + + + +# Error 40000: Bad request + +## What Happened + +Your request cannot be processed because it doesn't meet Ably's requirements - this could be due to invalid parameters, wrong connection state, missing prerequisites, or protocol violations. + +## Quick Reference + +| Error Code | HTTP Status | Category | Retryable | +|------------|-------------|----------|-----------| +| 40000 | 400 | Client Error (Various) | No - requires fixing the request | + +## Quick Fix + +- Check the specific error message for details about what's wrong +- Verify all parameters are the correct type and format +- Ensure the connection and channel are in the correct state for your operation +- Review feature enablement if using Chat SDK features + +## Error Messages + +You may see one of these messages: + + +- "Unable to publish in Suspended state" - Connection suspended after 2+ minutes disconnected +- "Message cannot be published. Client is not allowed to queue messages when connection is in Initialized state" - Message queueing is disabled +- "Channel is not attached" - Channel must be attached before operations +- "Invalid parameter: {parameter} must be {type}" - Wrong parameter type provided +- "Total recipients {count} exceeds maximum allowed 1000" - Push notification batch limit exceeded +- "Unable to read from transport: msg=invalid websocket message (decode failure)" - Protocol format error (.NET SDK) +- "options.params must be an object" - Invalid parameter type +- "options.modes must be an array" - Invalid channel modes format +- "room already exists with different options" - Room configuration conflict +- "cannot subscribe to occupancy; occupancy events are not enabled in room options" - Feature not enabled + + + +## Common Causes + +### 1. Input Validation Errors (40% of cases) +- **Wrong data types**: Providing string when object expected, or vice versa +- **Format violations**: Invalid timeserials, channel names, or client IDs +- **Missing required fields**: Required parameters not provided +- **Values out of range**: Message size exceeded, recipient count over limit + + + +### 2. State Prerequisites Not Met (30% of cases) +- **Publishing in suspended state**: Connection has been disconnected for over 2 minutes +- **Channel not attached**: Attempting operations before channel attachment +- **Connection not established**: Operations attempted before connection is ready +- **Message queueing disabled**: `queueMessages: false` prevents automatic queueing +- **Component lifecycle violations**: Operations on unmounted or disposed components + + + + +### 3. Resource Conflicts (15% of cases) +- **Duplicate resources**: Attempting to create already existing resources +- **Configuration conflicts**: Getting room with different options than originally specified +- **Immutable modifications**: Trying to change channel options after creation + + + +### 4. Protocol and Serialization Issues (10% of cases) +- **.NET SDK serialization**: Custom serializers sending enums as strings instead of integers +- **WebSocket message format**: Protocol messages improperly formatted +- **Batch format errors**: JSON sent instead of msgpack for batch operations + + + +### 5. Feature Not Enabled (5% of cases) +- **Presence operations**: Attempting presence without enabling in room options +- **Occupancy tracking**: Using occupancy features without enabling them +- **Typing indicators**: Starting typing without enabling the feature + + + +## Resolution Steps + +### 1. For State-Related Errors + +**If you see "Unable to publish in Suspended state":** + +1. The connection has been disconnected for over 2 minutes and entered suspended state +2. Create a new connection or wait for automatic recovery +3. Monitor connection state to prevent future suspensions +4. See [Connection state management documentation](https://ably.com/docs/realtime/connection#connection-state-recovery) + +**If you see "Message cannot be published" with connection state errors:** + +1. Check if `queueMessages` is set to `false` in your client options +2. If so, either: + - Enable message queueing (recommended): `new Ably.Realtime({ key: 'key', queueMessages: true })` + - Or wait for connection before publishing (only if queueing must be disabled) +3. With default settings, messages are automatically queued - this error indicates a configuration issue + +**For "Channel is not attached" errors:** +1. With default settings, messages are automatically queued - this error indicates a configuration issue +2. If you've disabled queueing (`queueMessages: false`), wait for attachment before operations +3. Review [Channel lifecycle documentation](https://ably.com/docs/channels) + + +### 2. For Parameter Validation Errors + +1. **Check the error message** for the specific parameter that failed +2. **Verify parameter types** match the API requirements: + - `options.params` must be an object, not a string + - `options.modes` must be an array + - Context parameters must be arrays of objects +3. **Validate channel names** against [naming requirements](https://ably.com/docs/channels#name-syntax) +4. **Check SDK documentation** for specific parameter formats + + +### 3. For .NET SDK Serialization Errors + +If you see "Unable to read from transport: msg=invalid websocket message (decode failure)": + + +1. **Check your custom serializers** - ensure enums serialize as integers, not strings +2. **Verify protocol message format** - action fields must be integers +3. **Review serialization configuration** for default settings +4. See the [.NET SDK serialization documentation](https://ably.com/docs/sdk/dotnet#custom-serialization) + +### 4. For Push Notification Recipient Limits + +If you see "Total recipients exceeds maximum allowed 1000": + + +1. **Batch your recipients** in groups of 1000 or fewer +2. **Implement batching logic** in your application +3. See [Push notification limits documentation](https://ably.com/docs/push/publish#recipient-limits) + +### 5. For Chat SDK Feature Errors + +1. **Enable required features** in room options before attempting operations +2. **Check room configuration** matches your intended use: + - Enable presence for presence operations + - Enable typing for typing indicators + - Enable occupancy for occupancy tracking +3. See [Chat room configuration documentation](https://ably.com/docs/chat/rooms#room-options) + + +### 6. For Timeserial Format Errors + +If you see errors about invalid timeserials: +1. **Check format**: Must contain `@` and `-` characters +2. **Structure**: `@-` +3. **Components**: All parts must be valid integers +4. See [Timeserial documentation](https://ably.com/docs/metadata-stats/metadata/subscribe#serial) + + +## Automatic Handling + +Ably SDKs do not automatically retry 40000 errors as they indicate issues with your request that must be fixed. The SDKs will: +- Preserve the full error message with specific details +- Maintain connection and channel states +- Not affect other operations or channels + +With default settings (`queueMessages: true`), messages are automatically queued during temporary disconnections, so you should rarely see state-related 40000 errors in normal operation. + + + +## Prevention + +- **Use default SDK settings** - Message queueing is enabled by default, preventing most state errors +- **Validate parameters** before API calls using TypeScript or runtime checks +- **Monitor connection states** to understand when operations are safe +- **Enable required features** upfront in room/channel options +- **Implement proper error handling** to catch and respond to validation failures +- **Use current SDK versions** to benefit from improved error handling +- **Test serialization** if using custom serializers in .NET SDK + + + +## Performance Impact + +This error prevents the specific operation but doesn't affect: +- Existing subscriptions on other channels +- Overall connection state (unless in suspended/failed state) +- Other clients or connections +- Message history already stored + +## Related Resources + +- [Connection state management](https://ably.com/docs/realtime/connection) +- [Channel parameters documentation](https://ably.com/docs/channels/options) +- [Push notification limits](https://ably.com/docs/push/publish#recipient-limits) +- [Chat room configuration](https://ably.com/docs/chat/rooms#room-options) +- [.NET SDK serialization](https://ably.com/docs/sdk/dotnet#custom-serialization) +- [Message queueing behavior](https://ably.com/docs/realtime/connection#queue-messages) +- Related errors: [80000](./80000-connection-failed.mdx), [80002](./80002-connection-suspended.mdx), [90000](./90000-channel-operation-failed.mdx) + +## Need Further Help? + +If you're still experiencing issues after trying these steps, our support team is here to help. + +**Contact Ably Support**: https://ably.com/support + +When contacting support, please provide: +- Your account ID and app ID +- The full error message including error code 40000 +- Steps to reproduce the issue +- Any relevant code snippets (without sensitive credentials) +- The SDK and version you're using + +Our team will help you resolve this issue as quickly as possible. + + + + + + + + + + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/40001-invalid-request-body.mdx b/src/pages/docs/platform/errors/codes/40001-invalid-request-body.mdx new file mode 100644 index 0000000000..b0d9d68be7 --- /dev/null +++ b/src/pages/docs/platform/errors/codes/40001-invalid-request-body.mdx @@ -0,0 +1,211 @@ + + + + + + + + +# Error 40001: Invalid request body + +## What Happened + +The request sent to Ably contains invalid, malformed, or incomplete data that cannot be processed. + +## Quick Reference + +| Error Code | HTTP Status | Category | Retryable | +|------------|-------------|----------|-----------| +| 40001 | 400 | Client Error (Validation) | No - requires fixing the request | + +## Quick Fix + +- Verify your request body is valid JSON or MessagePack format +- Ensure all required fields are present and not empty +- Check that your Content-Type header matches your request format + +## Error Messages + +You may encounter one of these specific error messages: + +- "invalid request body" +- "unable to publish chat message while parsing request; cannot decode request body (ensure JSON is properly formatted)" +- "unable to publish chat message while validating request; text is empty (message text field is required and cannot be empty)" +- "Invalid token request body while parsing authentication request; no keyName specified (keyName is required for token requests)" +- "Invalid token request body while parsing authentication request; no nonce specified (nonce is required to prevent replay attacks)" +- "unable to add message reaction; type is invalid" +- "unable to add message reaction; name is empty" +- "invalid JSON data" +- "invalid MessagePack data" +- "invalid utf-8 data" +- "missing content-type" +- "invalid response content-type" + +## Common Causes + +1. **Malformed request body** (40% of cases) + - Invalid JSON syntax + - Improperly encoded MessagePack data + - Invalid UTF-8 encoding in text fields + + +2. **Missing required fields** (35% of cases) + - Empty message text in chat operations + - Missing keyName in token requests + - Missing reaction name or type + - Missing nonce in non-key-authenticated token requests + + +3. **Missing or incorrect Content-Type header** (15% of cases) + - No Content-Type header in request + - Content-Type doesn't match actual request format + - Using unsupported content types (e.g., plain text, form-encoded) + + +4. **Invalid configuration values** (10% of cases) + - Non-positive typing throttle values + - Invalid reaction types + - Incompatible room configuration options + + +## Resolution Steps + +1. **Validate your request format** + - Ensure your JSON is properly formatted using a JSON validator + - Check for common syntax errors like missing quotes, commas, or brackets + - If using MessagePack, verify your encoding is correct + + +2. **Review required fields for your operation** + + For **chat messages**: + - Ensure the `text` field is present and not empty + - Include all required metadata fields + + + For **token requests**: + - Include the `keyName` parameter + - Add a unique `nonce` value for non-key-authenticated requests + + + For **reactions**: + - Provide both `type` and `name` fields when required + - Use only valid reaction types as documented + + +3. **Set proper HTTP headers** + - Include `Content-Type: application/json` for JSON requests + - Use `Content-Type: application/x-msgpack` for MessagePack + - Ensure character encoding is UTF-8 + + +4. **Check SDK-specific requirements** + - Review the API documentation for your specific SDK + - Verify you're using the correct method signatures + - Ensure proper serialization settings in your language + + +5. **Debug with minimal payload** + - Start with the simplest valid request + - Gradually add optional parameters + - Log the exact request body being sent + + +## Automatic Handling + +This is a client error that will not be automatically retried by Ably SDKs. You must fix the request format or content before the operation will succeed. + +## Prevention + +- Validate all input data before sending requests to Ably +- Use strongly-typed SDK methods where available +- Implement request validation in your application layer +- Test with various payload sizes and character sets +- Keep your SDK updated to the latest version + + +## Related Resources + +- [Ably REST API Documentation](https://ably.com/docs/api/rest-api) +- [Ably Chat API Documentation](https://ably.com/docs/chat) +- [Token Authentication Documentation](https://ably.com/docs/auth/token) +- [Message Encoding Documentation](https://ably.com/docs/general/encodings) +- Related errors: [40003](https://help.ably.io/error/40003), [40012](https://help.ably.io/error/40012), [40013](https://help.ably.io/error/40013) + +## Need Further Help? + +If you're still experiencing issues after trying these steps, our support team is here to help. + +**Contact Ably Support**: https://ably.com/support + +When contacting support, please provide: +- Your account ID and app ID +- The full error message including error code 40001 +- Steps to reproduce the issue +- Any relevant code snippets (without sensitive credentials) +- The SDK and version you're using + +Our team will help you resolve this issue as quickly as possible. + + + + + + + + + + + + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/40003-invalid-parameter-value.mdx b/src/pages/docs/platform/errors/codes/40003-invalid-parameter-value.mdx new file mode 100644 index 0000000000..81c8bddd1b --- /dev/null +++ b/src/pages/docs/platform/errors/codes/40003-invalid-parameter-value.mdx @@ -0,0 +1,451 @@ + + + + + + + + +# Error 40003: Invalid Parameter Value + +## What Happened + +A parameter in your request contains an invalid value that doesn't meet Ably's requirements. + +## Quick Reference + +| Error Code | HTTP Status | Category | Retryable | +|------------|-------------|----------|-----------| +| 40003 | 400 | Client Error (Validation) | No - requires fixing the parameter value | + +## Quick Fix + +- Check the specific error message for which parameter is invalid +- Verify the parameter meets documented constraints (type, format, range) +- Review the parameter requirements in the relevant API documentation + +## Error Messages + +You may see one of these messages: + + + + +**Token TTL Errors:** +- "Excessive value for ttl" - Token TTL exceeds 24-hour maximum +- "Excessive value for ttl (revocation is enabled on this key, and revocable tokens are limited to a TTL of one hour)" - Revocable token TTL exceeds 1-hour maximum + +**Encryption Errors:** +- "No key specified" - Missing encryption key +- "Unsupported keyLength. Only 128 and 256 bits are supported" - Invalid encryption key size +- "keyLength does not match the actual key length" - Declared key size doesn't match actual +- "Unsupported cipher configuration. The supported configurations are aes-128-cbc and aes-256-cbc" - Invalid cipher +- "The specified algorithm is not supported by openssl" - OpenSSL compatibility issue +- "Only 128 and 256 bit keys are supported" - Invalid key bit size (.NET) + +**LiveObjects Errors:** +- "Map key should be string" - LiveObjects map key is not a string +- "Map entries should be a key-value object" - Invalid object for setEntries +- "Counter value should be a valid number" - LiveObjects counter value is not numeric +- "Counter value increment should be a valid number" - Non-numeric increment value +- "Counter value decrement should be a valid number" - Non-numeric decrement value + +**History Query Errors:** +- "Unable to parse start parameter" - Invalid timestamp format in history query +- "Unable to parse end parameter" - Invalid timestamp format +- "Unable to parse limit parameter" - Non-integer limit value +- "Limit must be >0" - Zero or negative limit value +- "Start or end parameter was specified multiple times (ambiguous)" - Duplicate parameters +- "Invalid format param" - Unsupported format value +- "Unable to parse fromSerial parameter" - Invalid serial format + +**Message/Annotation Errors:** +- "Message data must be object or array when including annotations" - Incompatible message format +- "size of annotations field for batch should not exceed 4GB" - Annotations too large +- "Message serial can not be empty" - Missing serial for annotations +- "Message data must be either, string, string with binary data, JSON-encodable array or object, or null" - Invalid data type +- "Wrong parameters provided, use either Message, array of Messages, or name and data" - Invalid publish parameters + +**Other Validation Errors:** +- "invalid auth URL" - Invalid URL format in authentication +- "Unexpected offset format" - Invalid Cassandra offset format +- "Malformed history query options" - Invalid query structure +- "Unable to find filter.id expression" - Missing filter expression + +## Common Causes + + + + +1. **Token TTL exceeding limits** (Most common in production) + - Requesting token with TTL > 24 hours for standard tokens + - Requesting token with TTL > 1 hour for revocable tokens + - Not aware of different limits for revocable vs standard tokens + + + +2. **Invalid encryption parameters** (Common in PHP implementations) + - Missing encryption key when cipher is specified + - Unsupported key length (not 128 or 256 bits) + - Key length mismatch between declared and actual size + - OpenSSL version incompatibility + + +3. **LiveObjects type validation failures** (JavaScript/TypeScript applications) + - Non-string keys for LiveMap operations + - Non-numeric values for LiveCounter operations + - Invalid object structure for setEntries + - Type mismatches in batch operations + + +4. **History query parameter errors** + - Invalid timestamp formats for start/end parameters + - Non-integer or negative limit values + - Duplicate parameter specifications + - Malformed fromSerial values in chat history + + +5. **Message and annotation validation failures** + - Annotations exceeding 4GB size limit + - Empty message serials with annotations + - Incompatible data types with annotations + - Wrong parameter combinations in publish methods + + +## Resolution Steps + +### For Token TTL Errors + + + + +1. **Check your token request TTL** + ```javascript + // ❌ Wrong: TTL exceeds 24 hours + const tokenRequest = await ably.auth.createTokenRequest({ + ttl: 90000000 // 25 hours in milliseconds - will fail + }); + + // ✅ Correct: TTL within standard token limits + const tokenRequest = await ably.auth.createTokenRequest({ + ttl: 86400000 // 24 hours maximum for standard tokens + }); + + // ✅ Correct: Revocable token with appropriate limit + const tokenRequest = await ably.auth.createTokenRequest({ + ttl: 3600000, // 1 hour maximum for revocable tokens + // Note: revocation is configured on the API key, not in the request + }); + ``` + + +2. **Verify your API key configuration** + - Check if your API key has revocation enabled in the Ably dashboard + - Standard tokens: Maximum TTL is 24 hours (86400000 ms) + - Revocable tokens: Maximum TTL is 1 hour (3600000 ms) + - If you need longer-lived tokens, use a non-revocable API key + +3. **Consider your use case** + - For short-lived sessions: Use shorter TTLs (e.g., 1-2 hours) + - For long-running applications: Implement token renewal before expiry + - For revocable tokens: Plan for frequent renewal cycles + +### For Encryption Errors + + + + +1. **Provide a valid encryption key** + ```javascript + // ❌ Wrong: Missing key + const channel = ably.channels.get('encrypted', { + cipher: { algorithm: 'aes-128-cbc' } // Error: No key specified + }); + + // ✅ Correct: Include encryption key + const key = await generateCryptoRandomKey(128); // 128-bit key + const channel = ably.channels.get('encrypted', { + cipher: { + key: key, // Must be 128-bit or 256-bit + algorithm: 'aes-128-cbc' + } + }); + ``` + + +2. **Ensure correct key sizes** + - Only 128-bit (16 bytes) or 256-bit (32 bytes) keys are supported + - If specifying keyLength, ensure it matches actual key size + - Let the SDK auto-detect key size when possible + +3. **For PHP: Verify OpenSSL support** + ```php + // Check if required cipher is available + $methods = openssl_get_cipher_methods(); + if (!in_array('aes-256-cbc', $methods)) { + // Update OpenSSL or use aes-128-cbc instead + error_log('AES-256-CBC not supported, falling back to AES-128-CBC'); + $cipher = 'aes-128-cbc'; + } + ``` + + +### For LiveObjects Errors + + + +1. **Use correct data types for map operations** + ```javascript + // ❌ Wrong: Non-string map keys + liveMap.set(123, 'value'); // Error: Map key should be string + liveMap.set(null, 'value'); // Error: Map key should be string + + // ✅ Correct: String keys only + liveMap.set('123', 'value'); + liveMap.set('user-id', 'value'); + ``` + + +2. **Validate counter operations** + ```javascript + // ❌ Wrong: Non-numeric counter values + liveCounter.increment('five'); // Error: should be a valid number + liveCounter.set('100'); // Error: should be a valid number + + // ✅ Correct: Numeric values only + liveCounter.increment(5); + liveCounter.set(100); + liveCounter.decrement(1); + ``` + +3. **Structure setEntries correctly** + ```javascript + // ❌ Wrong: Invalid entries format + liveMap.setEntries('invalid'); // Error: should be a key-value object + liveMap.setEntries([1, 2, 3]); // Error: should be a key-value object + + // ✅ Correct: Valid key-value object + liveMap.setEntries({ + 'key1': 'value1', + 'key2': { nested: 'object' }, + 'key3': 123 + }); + ``` + +### For History Query Errors + + + + +1. **Use valid timestamp formats** + ```javascript + // ❌ Wrong: Invalid timestamp formats + const history = await channel.history({ + start: 'yesterday', // Error: Unable to parse + end: 'now', // Error: Unable to parse + limit: '10' // Error: Must be integer + }); + + // ✅ Correct: Valid millisecond timestamps and integer limit + const history = await channel.history({ + start: Date.now() - 3600000, // 1 hour ago (milliseconds) + end: Date.now(), // Current time + limit: 100, // Positive integer + direction: 'backwards' + }); + ``` + + +2. **Avoid duplicate parameters** + - Ensure start/end parameters appear only once in the query + - Use either query string OR options object, not both + - Check for accidental parameter duplication in HTTP requests + +3. **Validate limit values** + - Must be a positive integer (> 0) + - Maximum typically 1000 per request + - Use pagination for larger result sets + +### For Message and Annotation Errors + + + +1. **Ensure compatible message formats with annotations** + ```javascript + // ❌ Wrong: String data with annotations + channel.publish({ + name: 'message', + data: 'simple string', // Error: must be object or array + annotations: { ... } + }); + + // ✅ Correct: Object or array data with annotations + channel.publish({ + name: 'message', + data: { text: 'message content' }, // Object format + annotations: { timestamp: Date.now() } + }); + ``` + +2. **Provide message serials when required** + ```javascript + // ❌ Wrong: Empty serial with annotations + const message = { + serial: '', // Error: Message serial can not be empty + annotations: { ... } + }; + + // ✅ Correct: Valid serial value + const message = { + serial: 'unique-serial-123', + annotations: { ... } + }; + ``` + +3. **Use correct publish parameter patterns** + ```javascript + // ✅ Correct patterns for publishing: + + // Pattern 1: Name and data + channel.publish('event-name', { data: 'value' }); + + // Pattern 2: Single message object + channel.publish({ name: 'event', data: 'value' }); + + // Pattern 3: Array of messages + channel.publish([ + { name: 'event1', data: 'value1' }, + { name: 'event2', data: 'value2' } + ]); + ``` + +## Automatic Handling + +This is a client error that will not be automatically retried. You must fix the invalid parameter value before the operation will succeed. The SDKs will not attempt to correct or retry these validation errors. + +## Prevention + + + + +- **Validate parameters before API calls**: Check data types and ranges match API requirements +- **Use SDK validation methods**: Many SDKs provide built-in validation helpers +- **Test with minimal values first**: Start with known-good parameters during development +- **Check environment compatibility**: Ensure OpenSSL support for encryption operations (PHP) +- **Review API documentation**: Verify parameter constraints for each operation +- **Implement type checking**: Use TypeScript or runtime type validation for JavaScript +- **Monitor error patterns**: Track 40003 errors to identify common issues in your application +- **Use consistent timestamp formats**: Prefer milliseconds for all time-based parameters + +## Performance Impact + +While this error doesn't directly impact performance, repeated validation failures can: +- Delay application functionality +- Increase unnecessary API calls +- Create poor user experience with failed operations + +Consider implementing client-side validation to catch these errors before making API requests. + +## Related Resources + +- [Token Authentication](https://ably.com/docs/auth/token) +- [Encryption Guide](https://ably.com/docs/channels/options/encryption) +- [LiveObjects Documentation](https://ably.com/docs/products/liveobjects) +- [History API](https://ably.com/docs/storage-history/history) +- [API Limits](https://ably.com/docs/general/limits) +- [Message Formats](https://ably.com/docs/channels/messages) +- Related errors: [40001](./40001-invalid-request-body.mdx), [40004](./40004-invalid-header.mdx), [40005](./40005-invalid-credential.mdx), [40009](./40009-maximum-message-length-exceeded.mdx), [40012](./40012-invalid-client-id.mdx), [40013](./40013-invalid-message-data-or-encoding.mdx) + +## Need Further Help? + +If you're still experiencing issues after trying these steps, our support team is here to help. + +**Contact Ably Support**: https://ably.com/support + +When contacting support, please provide: +- Your account ID and app ID +- The full error message including error code 40003 +- Steps to reproduce the issue +- Any relevant code snippets (without sensitive credentials) +- The SDK and version you're using + +Our team will help you resolve this issue as quickly as possible. + + + + + + + + + + + + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/40004-invalid-header.mdx b/src/pages/docs/platform/errors/codes/40004-invalid-header.mdx new file mode 100644 index 0000000000..c9f0c203d6 --- /dev/null +++ b/src/pages/docs/platform/errors/codes/40004-invalid-header.mdx @@ -0,0 +1,175 @@ + + + + + + + + +# Error 40004: Invalid header + +## What Happened + +The server rejected your request due to an invalid or malformed header value that couldn't be parsed or validated. + +## Quick Reference + +| Error Code | HTTP Status | Category | Retryable | +|------------|-------------|----------|-----------| +| 40004 | 400 | Client Error (Validation) | No - requires fixing the header format | + +## Quick Fix + +- Check your HTTP headers for proper formatting and encoding +- Verify token TTL is within acceptable limits (≤1 hour) +- Ensure all required header attributes are present + +## Error Messages + +You may see one of these messages: +- "invalid header" +- "Invalid Link header" +- "Invalid Link header; missing rel" +- "Invalid Link header; missing params" +- "Invalid encoding" +- "Invalid encoding; missing format" +- "Invalid encoding; missing params" +- "Excessive value for ttl" + +## Common Causes + +1. **Invalid HTTP headers** (40% of cases) + - Malformed Content-Type headers that can't be parsed + - Link headers missing required attributes + - Non-UTF8 encoded header values + + +2. **Token TTL exceeds limits** (30% of cases) + - JWT tokens with TTL greater than 1 hour + - Platform validation incorrectly applied to embedded tokens + - Token expiry calculation issues + + +3. **Message encoding issues** (20% of cases) + - Invalid or missing encoding format specification + - Missing cipher parameters in encrypted messages + - Malformed encoding strings + + +4. **Auth callback issues** (10% of cases) + - Auth callback responses with invalid Content-Type headers + - Token authentication response header parsing failures + + +## Resolution Steps + +1. **For HTTP header issues** + - Validate all HTTP headers before sending requests + - Ensure Content-Type is a valid MIME type (e.g., "application/json", "text/plain") + - For Link headers, include both 'rel' and 'params' attributes + - Use proper UTF-8 encoding for all header values + + +2. **For token TTL issues** + - Ensure JWT token TTL is 1 hour or less + - Check token expiry time calculation (expiryTime - issuedTime) + - If using JWTs embedding Ably tokens, verify the surrounding JWT's TTL + - Review [Ably's token authentication documentation](https://ably.com/docs/auth/token) + + +3. **For message encoding issues** + - Include format specification in encoding strings + - Provide all required cipher parameters for encrypted messages + - Follow the expected encoding string pattern + - See [Ably's message encoding documentation](https://ably.com/docs/realtime/messages#message-encoding) + + +4. **For auth callback issues** + - Return valid Content-Type headers from auth callbacks + - Ensure headers are parseable MIME types + - Review your auth callback implementation + - Reference [Ably's auth callback documentation](https://ably.com/docs/auth/token#auth-callback) + + +## Automatic Handling + +This is a client error that will not be automatically retried. You must fix the header format or value before the request will succeed. + +## Prevention + +- Validate all headers before sending requests +- Use standard HTTP header formatting +- Keep JWT token TTL within 1 hour limit +- Test auth callbacks to ensure proper header formatting +- Follow Ably's encoding specifications for messages + +## Related Resources + +- [Authentication documentation](https://ably.com/docs/auth) +- [Token authentication guide](https://ably.com/docs/auth/token) +- [Message encoding](https://ably.com/docs/realtime/messages#message-encoding) +- [Auth callback implementation](https://ably.com/docs/auth/token#auth-callback) + +## Need Further Help? + +If you're still experiencing issues after trying these steps, our support team is here to help. + +**Contact Ably Support**: https://ably.com/support + +When contacting support, please provide: +- Your account ID and app ID +- The full error message including error code 40004 +- Steps to reproduce the issue +- Any relevant code snippets (without sensitive credentials) +- The SDK and version you're using + +Our team will help you resolve this issue as quickly as possible. + + + + + + + + + + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/40005-invalid-credential.mdx b/src/pages/docs/platform/errors/codes/40005-invalid-credential.mdx new file mode 100644 index 0000000000..96f622de7c --- /dev/null +++ b/src/pages/docs/platform/errors/codes/40005-invalid-credential.mdx @@ -0,0 +1,186 @@ + + + + + + + + +# Error 40005: Invalid credential + +## What Happened + +Your authentication credentials (API key or token) are invalid or incorrectly formatted. + +## Quick Reference + +| Error Code | HTTP Status | Category | Retryable | +|------------|-------------|----------|-----------| +| 40005 | 400/401 | Client Error (Authentication) | No - requires valid credentials | + +## Quick Fix + +- Verify your API key format matches: `appId.keyId:keySecret` +- Check that your API key hasn't been revoked in the Ably dashboard +- If using token authentication, ensure the token is correctly generated and not expired + +## Error Messages + +You may see one of these messages: +- "invalid credential" +- "API key format is invalid or malformed" +- "Invalid accessToken in request: [token details]" + +## Common Causes + +1. **Incorrect API key format** (60% of cases) + + - Missing components in the API key string + - API key not fully copied from dashboard + - Using only part of the key instead of the complete string + +2. **Token authentication issues** (25% of cases) + + - Token incorrectly formatted or URL-encoded + - Token generation process has errors + - Using an expired token + +3. **Cryptographic validation failures** (10% of cases) + + - HMAC key has invalid length + - Signature validation fails + +4. **Push notification deregistration** (5% of cases) + + - Occurs during Android push notification cleanup + - Often safely ignored per RSH3d2c1 specification + +## Resolution Steps + +### For API Key Authentication + +1. **Verify your API key format** + + - Log into your [Ably dashboard](https://ably.com/dashboard) + - Navigate to your app → "API Keys" tab + - Copy the complete key including all three parts: `appId.keyId:keySecret` + - Ensure you're not missing any characters when copying + +2. **Check API key permissions** + + - Verify you have admin or owner access to the account + - Confirm the key has the necessary capabilities for your operations + - Consider creating a new API key with appropriate permissions if needed + +3. **Validate in your code** + + - Ensure the API key is passed as a complete string + - Check that environment variables are correctly loaded + - Verify no extra spaces or newlines in the key string + +### For Token Authentication + +1. **Review token generation** + + - Ensure you're correctly requesting a valid token before using it with Ably + - Verify the token request includes all required parameters + - Check that the server generating tokens has valid API credentials + +2. **Check token format** + + - Ensure the token isn't being incorrectly URL-encoded + - Verify the token is a string, not a JSON object + - Confirm the token hasn't expired + +3. **Unity-specific considerations** + + - Known issues exist with token auth in Unity (Issue #1292) + - Ensure token is passed as a string, not URL-encoded JSON + - Consider using API key authentication as a temporary workaround + +### For Push Notification Context (Android) + + +During device deregistration, this error can be safely ignored as the SDK handles it gracefully according to specification RSH3d2c1. The deregistration will proceed despite the authentication failure. + +## Automatic Handling + +This is a client error that will not be automatically retried. You must provide valid credentials before the operation will succeed. + +## Prevention + +- Store API keys securely in environment variables or configuration files +- Implement token refresh logic before tokens expire +- Validate credential format before initializing the Ably SDK +- Use the Ably dashboard to monitor API key usage and permissions + +## Related Resources + +- [Authentication documentation](https://ably.com/docs/auth) +- [API Keys guide](https://ably.com/docs/auth#api-keys) +- [Token authentication](https://ably.com/docs/auth/token) +- Related errors: [40101 - Invalid credentials](https://help.ably.io/error/40101), [40170 - Invalid API key format](https://help.ably.io/error/40170) + +## Need Further Help? + +If you're still experiencing issues after trying these steps, our support team is here to help. + +**Contact Ably Support**: https://ably.com/support + +When contacting support, please provide: +- Your account ID and app ID +- The full error message including error code 40005 +- Steps to reproduce the issue +- Any relevant code snippets (without sensitive credentials) +- The SDK and version you're using + +Our team will help you resolve this issue as quickly as possible. + + + + + + + + + + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/40006-invalid-connection-id.mdx b/src/pages/docs/platform/errors/codes/40006-invalid-connection-id.mdx new file mode 100644 index 0000000000..b5630dd1dd --- /dev/null +++ b/src/pages/docs/platform/errors/codes/40006-invalid-connection-id.mdx @@ -0,0 +1,177 @@ + + + + + + + + +# Error 40006: Invalid connection ID + +## What Happened + +Your message contains an invalid connectionKey, mismatched connectionId, or the server cannot validate your connection identity. + +## Quick Reference + +| Error Code | HTTP Status | Category | Retryable | +|------------|-------------|----------|-----------| +| 40006 | 400 | Client Error (Validation) | No - requires fixing the connection parameters | + +## Quick Fix + +- Check if you're publishing on behalf of a realtime connection - ensure the connectionKey is current +- Verify your clientId is correctly set if using identified connections +- Ensure all SDKs are using compatible protocol versions when communicating cross-SDK + +## Error Messages + +You may see one of these messages: +- "Malformed message; invalid connectionKey" +- "Malformed message; invalid connectionId" +- "Malformed message; mismatched connectionId" +- "Malformed state message; invalid connectionId" +- "Malformed lastEvent" + +## Common Causes + + + +1. **Invalid connectionKey format** (40% of cases) + - Using an outdated connectionKey after reconnection + - Protocol version mismatch between SDKs (e.g., ably-ruby 1.2.3 with ably-js 1.2.35+) + - Malformed connectionKey string that doesn't match expected pattern + +2. **Missing or incorrect clientId** (35% of cases) + - Publishing on behalf of an identified connection without the correct clientId + - Authentication doesn't include the required clientId + - ClientId mismatch causes HMAC validation failure (but error message says "invalid connectionKey") + +3. **ConnectionId mismatch** (20% of cases) + - Message contains a connectionId that doesn't match the current connection + - Presence operations using an old connectionId after reconnection + - State messages with incorrect connectionId + +4. **Stateless connection issues** (5% of cases) + - Invalid lastEvent format when resuming a stateless connection + - Missing required timeseries prefix in lastEvent parameter + +## Resolution Steps + + + +1. **Identify the specific error scenario** + - Check the exact error message to determine if it's a connectionKey, connectionId, or lastEvent issue + - Note whether you're using REST API or realtime connections + - Check if connections are identified (have a clientId) + +2. **For connectionKey errors (REST publishing on behalf)** + + - Get the current connectionKey from the active realtime connection + - Ensure the connectionKey format matches your protocol version + - If using identified connections, verify the clientId is included in authentication + - Update SDKs to ensure protocol compatibility (protocol v2 in ably-js 1.2.35+) + +3. **For connectionId mismatches** + + - Don't set connectionId explicitly in your messages - let the SDK handle it + - For presence operations, re-enter presence after connection state changes + - Ensure state messages use the current connection's ID + +4. **For protocol version issues** + + - Update all SDKs to latest versions for protocol v2 support + - Ensure cross-SDK communication uses compatible versions + - Check [SDK compatibility documentation](https://ably.com/docs/sdks) + +5. **For clientId validation issues** + + - Verify your token or API key includes the correct clientId + - Ensure the clientId in your authentication matches what you're using + - Note: The error message may say "invalid connectionKey" even when the issue is clientId + +## Automatic Handling + +This is a validation error that will not be automatically retried. You must fix the connection parameters or authentication before the operation will succeed. + +## Prevention + + + +- Always use current connectionKeys when publishing on behalf of connections +- Let SDKs manage connectionId automatically - don't set it manually +- Keep all SDKs updated to ensure protocol compatibility +- Re-establish presence after connection state changes +- Include correct clientId in authentication for identified connections + +## Related Resources + +- [Connection state management](https://ably.com/docs/realtime/connection) +- [Publishing messages](https://ably.com/docs/rest/messages#publish) +- [Identified clients](https://ably.com/docs/auth/identified-clients) +- [Presence documentation](https://ably.com/docs/presence) +- Related errors: [40101](./40101-invalid-api-key.md) (authentication), [40103](./40103-invalid-use-of-basic-auth.md) (auth issues) + +## Need Further Help? + +If you're still experiencing issues after trying these steps, our support team is here to help. + +**Contact Ably Support**: https://ably.com/support + +When contacting support, please provide: +- Your account ID and app ID +- The full error message including error code 40006 +- Steps to reproduce the issue +- Any relevant code snippets (without sensitive credentials) +- The SDK and version you're using + +Our team will help you resolve this issue as quickly as possible. + + + + + + + + + + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/40008-invalid-content-length.mdx b/src/pages/docs/platform/errors/codes/40008-invalid-content-length.mdx new file mode 100644 index 0000000000..fe2143475c --- /dev/null +++ b/src/pages/docs/platform/errors/codes/40008-invalid-content-length.mdx @@ -0,0 +1,148 @@ + + + + + + + + +# Error 40008: Invalid content length + +## What Happened + +The request body size doesn't match the Content-Length header value declared in your HTTP request. + +## Quick Reference + +| Error Code | HTTP Status | Category | Retryable | +|------------|-------------|----------|-----------| +| 40008 | 400 | Client Error (Request Validation) | No - requires fixing the request | + +## Quick Fix + +- Ensure your HTTP client properly calculates the Content-Length header +- Check that your request body matches the declared content length exactly +- Consider using chunked transfer encoding for streaming data + +## Error Messages + +You may see this message: +- "Invalid content length" + +## Common Causes + +1. **Mismatched Content-Length header** (most common) + - The Content-Length header value doesn't match the actual request body size + - Data was truncated or expanded during transmission + - Client incorrectly calculated the content length + +2. **HTTP client issues** + - Proxy or middleware modifying the request body + - Network issues causing partial data transmission + - Encoding problems changing the byte size + +3. **Manual header setting** + - Manually setting Content-Length without proper byte calculation + - Character encoding differences affecting byte count + +## Resolution Steps + +1. **Let your HTTP client handle Content-Length automatically** + + - Most HTTP clients automatically calculate and set the Content-Length header + - Avoid manually setting this header unless necessary + +2. **If manually setting Content-Length, ensure accurate byte counting** + + - Calculate the exact byte length of your request body + - Be aware that character count may differ from byte count with multi-byte characters + - Test with various payload sizes to ensure correct calculation + +3. **Consider using chunked transfer encoding for dynamic content** + + - For streaming or dynamically generated content, use Transfer-Encoding: chunked + - This eliminates the need to know content size in advance + +4. **Check for intermediate proxies or middleware** + - Verify that no proxy servers are modifying your request + - Ensure any middleware isn't altering the request body after Content-Length is set + +## Automatic Handling + +This is a client error that will not be automatically retried. You must fix the Content-Length mismatch before the request will succeed. + +## Prevention + +- Use well-established HTTP client libraries that handle headers automatically +- Avoid manually setting Content-Length headers +- For custom implementations, thoroughly test byte counting logic +- Monitor for this error in production to catch edge cases + +## Related Resources + +- [Ably REST API documentation](https://ably.com/docs/api/rest-api) +- [HTTP request limits](https://ably.com/docs/general/limits#http) +- Related error: 40009 (Max content length exceeded) + +## Need Further Help? + +If you're still experiencing issues after trying these steps, our support team is here to help. + +**Contact Ably Support**: https://ably.com/support + +When contacting support, please provide: +- Your account ID and app ID +- The full error message including error code 40008 +- Steps to reproduce the issue +- Any relevant code snippets (without sensitive credentials) +- The SDK and version you're using + +Our team will help you resolve this issue as quickly as possible. + + + + + + + + + + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/40009-message-size-exceeded.mdx b/src/pages/docs/platform/errors/codes/40009-message-size-exceeded.mdx new file mode 100644 index 0000000000..f6670020a7 --- /dev/null +++ b/src/pages/docs/platform/errors/codes/40009-message-size-exceeded.mdx @@ -0,0 +1,191 @@ + + + + + + + + +# Error 40009: Message size exceeded + +## What Happened + +Your message exceeded the maximum size allowed for your Ably package tier. + +## Quick Reference + +| Error Code | HTTP Status | Category | Retryable | +|------------|-------------|----------|-----------| +| 40009 | 400/413 | Client Error (Message Validation) | No - requires reducing message size | + +## Quick Fix + +- Check your current package tier's size limit (16KB for Basic, 64KB for Standard) +- Reduce message size by removing unnecessary data or compressing content +- Split large messages into smaller chunks if needed +- Consider upgrading your package for higher limits + +## Error Messages + +You may see one of these messages: +- "Maximum message length exceeded" +- "Maximum size of messages that can be published at once exceeded (was X bytes; limit is Y bytes)" +- "Maximum message length exceeded (size was X bytes, limit is Y bytes)" +- "ObjectMessages size X exceeds maximum allowed size of Y bytes" +- "Max content length exceeded" + + +## Common Causes + +1. **Message exceeds package limit** (80% of cases) + - Basic tier: Messages over 16KB (16,384 bytes) + - Standard tier: Messages over 64KB (65,536 bytes) + - Enterprise tier: Messages over custom limit (up to 256KB) + + +2. **Batch publishing total size** (15% of cases) + - Combined size of all messages in batch exceeds limit + - Individual messages may be within limit but total exceeds it + + +3. **LiveObjects aggregate size** (5% of cases) + - Total size of all object messages exceeds limit + - State synchronization messages aggregate toward limit + + +## Resolution Steps + +1. **Identify your current size limit** + - Check your Ably dashboard for your package tier + - Basic: 16KB, Standard: 64KB, Enterprise: Custom (up to 256KB) + - See [Ably pricing limits documentation](https://ably.com/docs/platform/pricing/limits#app-limits) + + +2. **Reduce message size** + - Remove unnecessary fields from your data + - Compress data before sending (consider gzip for text) + - Use more efficient data formats (binary instead of JSON where appropriate) + + +3. **For batch publishing** + - Split large batches into smaller groups + - Monitor combined size of all messages in batch + - Note: The error applies to total batch size, not individual messages + + +4. **For large data requirements** + - Consider splitting data across multiple messages + - Use pagination for large datasets + - Store large content externally and send references + - Upgrade to a higher package tier if consistently hitting limits + + +5. **Implement client-side validation** + - Check message size before sending to avoid network round-trip + - Calculate total size including metadata overhead + - Provide user feedback before attempting to publish + + +## Automatic Handling + +Ably SDKs validate message size client-side before sending to prevent unnecessary network requests. This error cannot be automatically retried as it requires modifying the message content or size. + + +## Prevention + +- **Monitor message sizes**: Track typical message sizes in your application +- **Set application limits**: Validate content size before creating messages +- **Use compression**: Compress large text payloads before sending +- **Design for limits**: Structure your data model with size limits in mind +- **Regular testing**: Test with production-like data volumes + + +## Performance Impact + +This error prevents message publishing but doesn't affect: +- Existing channel subscriptions +- Connection state +- Other channels or messages +- Message consumption by subscribers + +However, batch publishing failures may require resending the entire batch after size adjustment. + + +## Related Resources + +- [Ably pricing and limits](https://ably.com/docs/platform/pricing/limits#app-limits) +- [Message batching documentation](https://ably.com/docs/rest/messages#batch) +- [LiveObjects documentation](https://ably.com/docs/products/liveobjects) +- [Compression best practices](https://ably.com/docs/best-practice#compression) + +## Need Further Help? + +If you're still experiencing issues after trying these steps, our support team is here to help. + +**Contact Ably Support**: https://ably.com/support + +When contacting support, please provide: +- Your account ID and app ID +- The full error message including error code 40009 +- Steps to reproduce the issue +- Any relevant code snippets (without sensitive credentials) +- The SDK and version you're using + +Our team will help you resolve this issue as quickly as possible. + + + + + + + + + + + + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/40010-invalid-channel-name.mdx b/src/pages/docs/platform/errors/codes/40010-invalid-channel-name.mdx new file mode 100644 index 0000000000..1ea890eabc --- /dev/null +++ b/src/pages/docs/platform/errors/codes/40010-invalid-channel-name.mdx @@ -0,0 +1,214 @@ + + + + + + + + +# Error 40010: Invalid channel name + +## What Happened + +The channel name you provided doesn't meet Ably's naming requirements or contains invalid characters or qualifiers. + +## Quick Reference + +| Error Code | HTTP Status | Category | Retryable | +|------------|-------------|----------|-----------| +| 40010 | 400 | Client Error (Channel) | No - requires fixing the channel name | + +## Quick Fix + +- Remove any square brackets `[` from the start of your channel name +- Ensure your channel name isn't empty or contains only special characters like `:` +- Check that you're not mixing incompatible channel qualifiers + +## Error Messages + +You may see one of these messages: +- "Invalid channel name" +- "regex match failed" +- "cannot use a derived option with a {type} channel" +- "unable to attach to channel; invalid channel name" +- "Invalid qualifier in channelId; {qualifier}" +- "resource: invalid name {name}" +- "resource: invalid directive {directive}" +- "resource: invalid scope {scope}" +- "resource: invalid qualifier {qualifier}" + +## Common Causes + +1. **Channel name starts with square brackets** (60% of cases) + + - Using `[` at the beginning of the channel name + - Square brackets are reserved for channel qualifiers + - Example: `[mychannel]` instead of `mychannel` + +2. **Empty or invalid channel names** (20% of cases) + + - Using just `:` as a channel name + - Empty channel names + - Channel names with only special characters + +3. **Incompatible channel qualifiers** (15% of cases) + + - Trying to use derived options with already-qualified channels + - Using qualifiers that don't support client attachment + - Mixing incompatible qualifier types + +4. **Malformed resource identifiers** (5% of cases) + + - Invalid scope format in resource IDs + - Invalid directives in resource names + - Malformed qualifier strings + +## Resolution Steps + +1. **Fix channel names starting with square brackets** + + ```javascript + // ❌ Wrong: Square brackets at the start + const channel = ably.channels.get('[mychannel]'); + + // ✅ Correct: No leading square brackets + const channel = ably.channels.get('mychannel'); + + // ✅ Correct: Qualifiers use specific syntax + const metaChannel = ably.channels.get('[meta]mychannel'); + ``` + +2. **Ensure channel names are valid** + + ```javascript + // ❌ Wrong: Empty or special character only names + const channel1 = ably.channels.get(':'); + const channel2 = ably.channels.get(''); + + // ✅ Correct: Valid channel names + const channel1 = ably.channels.get('chat-room'); + const channel2 = ably.channels.get('user-123-updates'); + const channel3 = ably.channels.get('channel with spaces'); // Spaces are allowed + ``` + +3. **Check qualifier compatibility** + + ```javascript + // ❌ Wrong: Mixing incompatible qualifiers + // Don't try to add derived options to already-qualified channels + + // ✅ Correct: Use qualifiers as documented + const metaChannel = ably.channels.get('[meta]channel'); + const filteredChannel = ably.channels.get('[filter=headers.user-id==123]channel'); + ``` + +4. **Validate channel names before use** + + ```javascript + function validateChannelName(name) { + // Channel names cannot start with '[' + if (name.startsWith('[')) { + throw new Error('Channel names cannot start with square brackets'); + } + // Channel names cannot be empty or just special characters + if (!name || name === ':') { + throw new Error('Invalid channel name'); + } + return true; + } + + try { + const channelName = getUserInput(); + validateChannelName(channelName); + const channel = ably.channels.get(channelName); + } catch (error) { + console.error('Invalid channel name:', error.message); + } + ``` + +## Automatic Handling + +This is a client error that will not be automatically retried. You must fix the channel name format before the operation will succeed. + +## Channel Naming Rules + + +According to Ably's channel naming requirements: +- Channel names can contain any Unicode character, including spaces +- Channel names **cannot** start with square brackets `[` +- Square brackets are reserved for channel qualifiers (metadata/instructions to Ably) +- Valid qualifiers include `[meta]`, `[filter]`, `[persisted]`, and others + +For complete channel naming documentation, see [Channel naming documentation](https://ably.com/docs/channels#name-syntax). + +## Related Resources + +- [Channel documentation](https://ably.com/docs/channels) +- [Channel qualifiers](https://ably.com/docs/channels#qualifiers) +- [Channel naming restrictions](https://knowledge.ably.com/what-restrictions-are-there-on-channel-names) +- Related errors: [40000](./40000-bad-request.md), [40400](./40400-not-found.md) + +## Need Further Help? + +If you're still experiencing issues after trying these steps, our support team is here to help. + +**Contact Ably Support**: https://ably.com/support + +When contacting support, please provide: +- Your account ID and app ID +- The full error message including error code 40010 +- Steps to reproduce the issue +- Any relevant code snippets (without sensitive credentials) +- The SDK and version you're using + +Our team will help you resolve this issue as quickly as possible. + + + + + + + + + + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/40011-stale-ring-state.mdx b/src/pages/docs/platform/errors/codes/40011-stale-ring-state.mdx new file mode 100644 index 0000000000..4d14b3ca7e --- /dev/null +++ b/src/pages/docs/platform/errors/codes/40011-stale-ring-state.mdx @@ -0,0 +1,178 @@ + + + + + + + + +# Error 40011: Stale ring state or invalid data payload + +## What Happened + +This error has two distinct causes: either the channel enumeration API encountered a cluster state change during pagination, or a message contained an unsupported data type. + +## Quick Reference + +| Error Code | HTTP Status | Category | Retryable | +|------------|-------------|----------|-----------| +| 40011 | 400 | Client Error (Validation) | No - requires fixing the request | + +## Quick Fix + +- For channel enumeration: Restart enumeration from the beginning +- For message publishing: Ensure message data is a supported type (string, object, array, or binary) +- Check the specific error message to determine which scenario applies + +## Error Messages + +You may see one of these messages: +- "stale ring state" - Channel enumeration pagination became invalid +- "Invalid data payload" - Message data type not supported (Python SDK) + +## Common Causes + +### 1. Channel Enumeration Pagination Issue (Most Common) + +When using the [channel enumeration API](https://ably.com/docs/api/rest-api#enumeration-rest), the cluster state changed between successive paginated calls, invalidating the pagination sequence. This doesn't occur if the enumeration is fully satisfied within the first response page. + +### 2. Invalid Message Data Type (Python SDK) + +In the Python SDK, attempting to publish a message with unsupported data types. Supported types are: bytes, str, list, dict, bytearray, or None. + +## Resolution Steps + +### For Channel Enumeration Issues + +1. **Restart the enumeration** + + - When you receive this error, start the enumeration again from the beginning + - The cluster state has changed, making your current pagination cursor invalid + +2. **Optimize your enumeration strategy** + - Request larger page sizes to minimize pagination needs + - Consider caching enumeration results with an appropriate TTL + - Implement automatic retry logic that restarts from the beginning + +3. **Handle the error gracefully** + ```javascript + // Example retry logic for channel enumeration + async function enumerateChannels() { + try { + // Your enumeration logic here + } catch (error) { + if (error.code === 40011) { + // Restart enumeration from beginning + return enumerateChannels(); + } + throw error; + } + } + ``` + + +### For Invalid Data Payload (Python SDK) + +1. **Validate your message data type** + + - Ensure your data is one of: bytes, str, list, dict, bytearray, or None + - Primitive numbers and custom objects are not directly supported + +2. **Convert unsupported types** + ```python + # Convert numbers to strings or include in dict + # ❌ Wrong: Publishing a raw number + channel.publish('event', 42) # Will raise error 40011 + + # ✅ Correct: Convert to supported type + channel.publish('event', str(42)) # As string + channel.publish('event', {'value': 42}) # In dict + ``` + + +## Automatic Handling + +This is a client error that will not be automatically retried. You must: +- For enumeration: Restart from the beginning +- For data validation: Fix the data type before retrying + +## Prevention + +### Channel Enumeration + +- Request larger page sizes to complete enumeration in a single request when possible +- Build retry logic into your enumeration code +- Consider whether you need real-time enumeration or if cached results would suffice + +### Message Publishing +- Always validate data types before publishing +- Use SDK-appropriate data structures +- Implement type checking in your application code + +## Related Resources + +- [Channel Enumeration API](https://ably.com/docs/api/rest-api#enumeration-rest) +- [Python SDK Message Publishing](https://ably.com/docs/realtime/messages#publish) +- [Ably API Error Codes](https://ably.com/docs/platform/errors/codes) +- Related errors: [40000](./40000-bad-request.md) (Bad Request), [40013](./40013-invalid-message-data.md) (Invalid message data) + +## Need Further Help? + +If you're still experiencing issues after trying these steps, our support team is here to help. + +**Contact Ably Support**: https://ably.com/support + +When contacting support, please provide: +- Your account ID and app ID +- The full error message including error code 40011 +- Steps to reproduce the issue +- Any relevant code snippets (without sensitive credentials) +- The SDK and version you're using + +Our team will help you resolve this issue as quickly as possible. + + + + + + + + + + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/40012-invalid-client-id.mdx b/src/pages/docs/platform/errors/codes/40012-invalid-client-id.mdx new file mode 100644 index 0000000000..8c49fbf505 --- /dev/null +++ b/src/pages/docs/platform/errors/codes/40012-invalid-client-id.mdx @@ -0,0 +1,225 @@ + + + + + + + + +# Error 40012: Invalid client ID + +## What Happened + +Your request contains a client ID that doesn't meet Ably's validation requirements or conflicts with your authenticated identity. + +## Quick Reference + +| Error Code | HTTP Status | Category | Retryable | +|------------|-------------|----------|-----------| +| 40012 | 400 | Client Error (Authentication) | No - requires fixing client ID configuration | + +## Quick Fix + +- Remove the client ID from your message if it's already set via authentication +- Ensure your client ID is a non-empty string (not "" or null in messages) +- Don't use "*" as a client ID except in token parameters for wildcard capability + +## Error Messages + +You may see one of these messages: +- "invalid client id" +- "clientId can't be an empty string" +- "clientId must be either a string or null" +- "Can't use \"*\" as a clientId as that string is reserved" +- "clientId provided in ClientOptions must match clientId in token" +- "Incompatible clientId specified in message" +- "clientId must be specified to enter or leave a presence channel" +- "invalid clientId; must be base64 encoded if passed by header" + +## Common Causes + +1. **Empty string as client ID** (35% of cases) + - Using "" instead of a proper string value + - Not setting client ID when required for presence + + +2. **Client ID mismatch** (30% of cases) + - Token client ID differs from configured client ID + - Message client ID conflicts with authenticated client ID + - Client options specify different client ID than token + + +3. **Wildcard "*" misuse** (20% of cases) + - Using "*" as a regular client ID instead of in token parameters + - Attempting to initialize REST client with wildcard client ID + + +4. **Missing client ID for presence** (10% of cases) + - Attempting presence operations without authenticated client ID + - Not setting client ID before enter/leave/update operations + + +5. **Invalid type or encoding** (5% of cases) + - Client ID is not a string or null + - Missing base64 encoding when passed via header + + +## Resolution Steps + +1. **For empty client ID errors** + - Provide a non-empty string for your client ID + - If client ID is optional in your context, use null instead of "" + + +2. **For client ID mismatch errors** + - Ensure your token and client options use the same client ID: + ```javascript + // ❌ Wrong: Mismatched client IDs + const ably = new Ably.Realtime({ + key: 'your-api-key', + clientId: 'user-123' // This conflicts with token + }); + + // ✅ Correct: Let token set the client ID + const ably = new Ably.Realtime({ + key: 'your-api-key' + // Client ID will be set from token + }); + ``` + + +3. **For wildcard client ID errors** + - Use wildcard only in token parameters, not as regular client ID: + ```javascript + // ❌ Wrong: Using wildcard as regular client ID + const ably = new Ably.Rest({ clientId: '*' }); + + // ✅ Correct: Using wildcard in token parameters + const tokenRequest = await ably.auth.createTokenRequest({ + clientId: '*', // Allows publishing on behalf of any client + capability: { '*': ['publish', 'subscribe'] } + }); + ``` + + +4. **For presence operations** + - Always set client ID before presence operations: + ```javascript + // ❌ Wrong: No client ID for presence + const ably = new Ably.Realtime({ key: 'your-api-key' }); + channel.presence.enter(); // Will fail + + // ✅ Correct: Client ID configured + const ably = new Ably.Realtime({ + key: 'your-api-key', + clientId: 'user-123' + }); + channel.presence.enter(); // Will succeed + ``` + + +5. **For publishing messages** + - Don't set client ID in messages when already authenticated: + ```javascript + // ❌ Wrong: Manually setting client ID in message + channel.publish({ + name: 'message', + data: 'Hello', + clientId: 'user-123' // Remove this! + }); + + // ✅ Correct: Let Ably set it automatically + channel.publish({ + name: 'message', + data: 'Hello' + // Client ID is set automatically from authentication + }); + ``` + + +6. **For header encoding issues** + - When using X-Ably-Clientid header, base64 encode the value + - Alternatively, use query parameter clientId (no encoding needed) + + +## Automatic Handling + +This is a client error that will not be automatically retried. You must fix the client ID configuration issue before the operation will succeed. + +## Prevention + +- **Client-side**: Never set clientId explicitly in messages when already authenticated +- **Server-side**: Use wildcard clientId capability for multi-user publishing +- **Tokens**: Include clientId in token generation for user-specific connections +- **Presence**: Always configure clientId before attempting presence operations +- **Validation**: Ensure clientId is either a non-empty string or null (not undefined or other types) + +## Related Resources + +- [Authentication documentation](https://ably.com/docs/auth) +- [Client ID explained](https://ably.com/docs/auth/identified-clients) +- [Presence documentation](https://ably.com/docs/presence) +- [Token authentication](https://ably.com/docs/auth/token) + +## Need Further Help? + +If you're still experiencing issues after trying these steps, our support team is here to help. + +**Contact Ably Support**: https://ably.com/support + +When contacting support, please provide: +- Your account ID and app ID +- The full error message including error code 40012 +- Steps to reproduce the issue +- Any relevant code snippets (without sensitive credentials) +- The SDK and version you're using + +Our team will help you resolve this issue as quickly as possible. + + + + + + + + + + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/40101-invalid-credentials.mdx b/src/pages/docs/platform/errors/codes/40101-invalid-credentials.mdx new file mode 100644 index 0000000000..5ebf5b3c8a --- /dev/null +++ b/src/pages/docs/platform/errors/codes/40101-invalid-credentials.mdx @@ -0,0 +1,219 @@ + + + + + + + + +# Error 40101: Invalid credentials + +## What Happened + +Your authentication credentials are invalid or incorrectly formatted, preventing access to Ably services. + +## Quick Reference + +| Error Code | HTTP Status | Category | Retryable | +|------------|-------------|----------|-----------| +| 40101 | 401 | Authentication | No - requires fixing credentials | + +## Quick Fix + +- Verify your API key is complete and correctly formatted: `[AppId].[keyId]:[keySecret]` +- Check for typos or missing characters in your API key +- Ensure clientId matches between token generation and client initialization + +## Error Messages + +You may see one of these messages: +- "Invalid credentials" +- "No key specified" +- "Invalid key specified" +- "Ably key was empty. Ably key must be in the following format [AppId].[keyId]:[keyValue]" +- "Request mac does not match" +- "Invalid clientId for credentials" +- "Unable to set different clientId from that given in options" +- "Unable to handle request no application id found in request" + +## Common Causes + +1. **Incorrect API key format** (70% of cases) + + - Missing characters or typos in the API key + - Key doesn't follow format: `[AppId].[keyId]:[keySecret]` + - Empty or whitespace-only key string + - Copy-paste errors with leading/trailing spaces + +2. **Token MAC verification failures** (20% of cases) + + - Altered token request JSON after signature generation + - Incorrect key used for token generation + - Token tampering or corruption during transmission + +3. **ClientId mismatches** (10% of cases) + + - Different clientId between token and client constructor + - Attempting to change clientId on existing connection + - Empty or wildcard clientId when binding is required + +## Resolution Steps + +1. **Verify your API key format** + + - Log into your [Ably dashboard](https://ably.com/dashboard) + - Navigate to your app → "API Keys" tab + - Copy the complete key including all three parts: + - App ID (e.g., `xVLyHw`) + - Key ID (e.g., `rPSJgQ`) + - Key Secret (e.g., `U6RN3LJvZzV3DXJk`) + - Full format: `xVLyHw.rPSJgQ:U6RN3LJvZzV3DXJk` + +2. **Check your implementation** + + - Remove any leading or trailing whitespace from the key + - Ensure the key contains exactly one period (.) and one colon (:) + - Verify environment variables are loading correctly if used + +3. **For token authentication issues** + + - Ensure the token request JSON hasn't been modified after MAC generation + - Verify the same API key is used for both token generation and verification + - Check that clientId in token matches clientId in client options + - For JWT, confirm clientId is set in the x-ably-clientId header + +4. **Debug authentication problems** + + - Enable debug logging in your SDK to see detailed authentication flow + - Check for browser extensions or proxies that might strip Authorization headers + - Test with a fresh API key to rule out key-specific issues + +## Automatic Handling + +This is a client error that will not be automatically retried. You must fix the authentication configuration before the operation will succeed. The SDK will not attempt to recover from invalid credentials as this indicates a configuration issue rather than a transient problem. + +## Code Examples + +### Correct API Key Format + +```javascript +// ✅ Correct: Complete API key with all three parts +const ably = new Ably.Realtime('xVLyHw.rPSJgQ:U6RN3LJvZzV3DXJk'); + +// ❌ Wrong: Missing app ID +const ably = new Ably.Realtime('rPSJgQ:U6RN3LJvZzV3DXJk'); + +// ❌ Wrong: Missing key secret +const ably = new Ably.Realtime('xVLyHw.rPSJgQ'); + +// ❌ Wrong: Incomplete key with typo +const ably = new Ably.Realtime('xVLyHw.rPSJ:U6RN3LJvZzV3DXJk'); +``` + +### ClientId Configuration + +```javascript +// ✅ Correct: Consistent clientId +const tokenParams = { clientId: 'user123' }; +const token = await ably.auth.requestToken(tokenParams); + +const client = new Ably.Realtime({ + token: token, + clientId: 'user123' // Must match token clientId +}); + +// ❌ Wrong: Mismatched clientId +const client = new Ably.Realtime({ + token: token, + clientId: 'differentUser' // Will cause 40101 error +}); +``` + +## Related Resources + +- [Authentication documentation](https://ably.com/docs/auth) +- [API key best practices](https://ably.com/docs/auth/basic) +- [Token authentication guide](https://ably.com/docs/auth/token) +- [Client ID explained](https://ably.com/docs/auth/identified-clients) +- Related errors: [40102 - Token expired](https://help.ably.io/error/40102), [40400 - Not found](https://help.ably.io/error/40400) + +## Need Further Help? + +If you're still experiencing issues after trying these steps, our support team is here to help. + +**Contact Ably Support**: https://ably.com/support + +When contacting support, please provide: +- Your account ID and app ID +- The full error message including error code 40101 +- Steps to reproduce the issue +- Any relevant code snippets (without sensitive credentials) +- The SDK and version you're using + +Our team will help you resolve this issue as quickly as possible. + + + + + + + + + + + + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/40133-token-revocation-authorization-error.mdx b/src/pages/docs/platform/errors/codes/40133-token-revocation-authorization-error.mdx new file mode 100644 index 0000000000..b994cdea28 --- /dev/null +++ b/src/pages/docs/platform/errors/codes/40133-token-revocation-authorization-error.mdx @@ -0,0 +1,172 @@ + + + + + + + + +# Error 40133: Token revocation authorization error + +## What Happened + +You're attempting to revoke tokens using a different API key than the one that originally issued them. + +## Quick Reference + +| Error Code | HTTP Status | Category | Retryable | +|------------|-------------|----------|-----------| +| 40133 | 401 | Client Error (Authentication) | No - requires using the correct API key | + +## Quick Fix + +- Use the same API key that originally issued the tokens +- Verify your key ID matches the token's issuing key +- Ensure your key has token revocation capabilities enabled + +## Error Messages + +You'll see this exact message: +- "Can only revoke tokens using the same key that issued them" + +## Common Causes + +1. **Wrong API key** (80% of cases) + - Using Key B to revoke tokens issued by Key A + - Attempting revocation with an administrative key for tokens issued by a service key + - Key rotation without proper token tracking + +2. **Configuration errors** (15% of cases) + - Incorrect key selection in revocation requests + - Mixed up key IDs in multi-environment setups + - Copy-paste errors when setting up revocation requests + +3. **Process confusion** (5% of cases) + - Not tracking which key issued which tokens + - Attempting bulk revocation with a single key for tokens from multiple keys + - Misunderstanding the token-key relationship requirements + +## Resolution Steps + +1. **Identify the issuing key** + - Check your application logs for token issuance records + - Review your token tracking system if you have one + - Look up the token metadata to find the issuing key ID + + +2. **Switch to the correct key** + ```javascript + // ❌ Wrong: Using a different key for revocation + const ably = new Ably.Rest({ key: 'differentKey.id:secret' }); + await ably.auth.revokeTokens({ keyName: 'originalKey.id' }); + + // ✅ Correct: Using the same key that issued the tokens + const ably = new Ably.Rest({ key: 'originalKey.id:secret' }); + await ably.auth.revokeTokens({ keyName: 'originalKey.id' }); + ``` + + +3. **Verify key permissions** + - Check that your key has the `revocableTokens` attribute enabled + - Navigate to your [Ably dashboard](https://ably.com/dashboard) → API Keys + - Confirm the key has token revocation capabilities + + +4. **Test the revocation** + - Attempt revocation with the correct key + - Verify tokens are successfully invalidated + - Monitor for successful revocation confirmation + +## Automatic Handling + +This is a client error that will not be automatically retried. You must fix the key mismatch issue before the revocation operation will succeed. + +## Prevention + +- **Implement token tracking**: Maintain records mapping tokens to their issuing keys +- **Document key purposes**: Clearly document which keys are used for which operations +- **Standardize processes**: Establish clear procedures for token lifecycle management +- **Key rotation planning**: Before rotating keys, revoke existing tokens with the current key +- **Regular audits**: Review token issuance and revocation patterns periodically + + +## Key Rotation Best Practices + +When rotating API keys: + +1. **Before rotation**: Revoke all existing tokens using the current key +2. **During rotation**: Create the new key with appropriate permissions +3. **After rotation**: Issue new tokens only with the new key +4. **Never mix**: Don't attempt to revoke old tokens with new keys + + + +## Related Resources + +- [Token Revocation documentation](https://ably.com/docs/auth/revocation) +- [API Key Management](https://ably.com/docs/auth/api-key) +- [Authentication guide](https://ably.com/docs/auth) +- Related errors: [40162](https://help.ably.io/error/40162), [40164](https://help.ably.io/error/40164) + +## Need Further Help? + +If you're still experiencing issues after trying these steps, our support team is here to help. + +**Contact Ably Support**: https://ably.com/support + +When contacting support, please provide: +- Your account ID and app ID +- The full error message including error code 40133 +- Steps to reproduce the issue +- Any relevant code snippets (without sensitive credentials) +- The SDK and version you're using + +Our team will help you resolve this issue as quickly as possible. + + + + + + + + + + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/40140-token-error-unspecified.mdx b/src/pages/docs/platform/errors/codes/40140-token-error-unspecified.mdx new file mode 100644 index 0000000000..d223ff4201 --- /dev/null +++ b/src/pages/docs/platform/errors/codes/40140-token-error-unspecified.mdx @@ -0,0 +1,173 @@ + + + + + + + + +# Error 40140: Token error (unspecified) + +## What Happened + +Your authentication token could not be validated, and the specific reason couldn't be determined. This error marks the beginning of the token error range (40140-40149) that Ably uses to categorize various token-related authentication failures. + +## Quick Reference + +| Error Code | HTTP Status | Category | Retryable | +|------------|-------------|----------|-----------| +| 40140 | 401 | Authentication (Token) | No - requires new valid token | + +## Quick Fix + +- Request a new authentication token from your server +- Verify your token generation process is working correctly +- Check that your token hasn't expired or been revoked + +## Error Messages + +You may see one of these messages: +- "token error (unspecified)" +- "Token expired" +- Authentication failure messages with error code 40140 + +## Common Causes + +1. **Expired token** (most common) + - Token has exceeded its TTL (time to live) + - Token was valid when created but expired during use + + +2. **Invalid token format** + - Token structure is corrupted or malformed + - Token was incorrectly generated or transmitted + + +3. **Permission issues** + - Token lacks required capabilities for the operation + - Token was created with insufficient permissions + + +4. **Unspecified token problem** + - Generic token validation failure + - System couldn't determine the specific token issue + + +## Resolution Steps + +1. **Request a new token immediately** + - Have your server generate a fresh authentication token + - Ensure the token includes all required capabilities + - Replace the expired/invalid token in your client + + +2. **Verify token generation** + - Check your server-side token creation logic + - Ensure you're using the correct API key for token generation + - Verify the token request parameters are correct + + +3. **Implement token refresh** + - Set up automatic token renewal before expiration + - Monitor token TTL and refresh proactively + - Handle token errors gracefully in your application + + +4. **For SSE connections** + ```javascript + eventSource.onerror = msg => { + const err = JSON.parse(msg.data); + const isTokenErr = err.code >= 40140 && err.code < 40150; + if(isTokenErr) { + eventSource.close(); + // Fetch new token and reconnect + } + } + ``` + + +## Automatic Handling + +Ably SDKs automatically detect token errors in the 40140-40149 range and: +- Clear any cached token details to prevent reuse +- Attempt to obtain a new token if a token callback is configured +- Will not automatically retry without a valid token + + +## Prevention + +- **Implement proactive token refresh**: Renew tokens before they expire +- **Monitor token lifecycle**: Track token creation and expiration times +- **Use appropriate TTLs**: Balance security with user experience +- **Handle the 40140-40149 range**: Set up specific error handling for all token errors + + +## Related Resources + +- [Token Authentication Documentation](https://ably.com/docs/auth/token) +- [Authentication Guide](https://ably.com/docs/auth) +- [Token Capabilities](https://ably.com/docs/auth/capabilities) +- Related errors: 40141-40149 (specific token error types) + +## Need Further Help? + +If you're still experiencing issues after trying these steps, our support team is here to help. + +**Contact Ably Support**: https://ably.com/support + +When contacting support, please provide: +- Your account ID and app ID +- The full error message including error code 40140 +- Steps to reproduce the issue +- Any relevant code snippets (without sensitive credentials) +- The SDK and version you're using + +Our team will help you resolve this issue as quickly as possible. + + + + + + + + + + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/40142-token-expired.mdx b/src/pages/docs/platform/errors/codes/40142-token-expired.mdx new file mode 100644 index 0000000000..600d4cc0d2 --- /dev/null +++ b/src/pages/docs/platform/errors/codes/40142-token-expired.mdx @@ -0,0 +1,185 @@ + + + + + + + + +# Error 40142: Token expired + +## What Happened? + +Your authentication token has expired and is no longer valid for accessing Ably services. + +## Quick Reference + +| Error Code | HTTP Status | Category | Retryable | +|------------|-------------|----------|-----------| +| 40142 | 401 | Authentication | Yes - after token refresh | + +## Quick Fix + +- Request a new authentication token from your auth endpoint +- Replace the expired token in your Ably client configuration +- Implement automatic token refresh to prevent future expirations + +## Error Messages + +You may see one of these messages: +- "Token expired" +- "Token expired. (See https://help.ably.io/error/40142 for help.)" +- In SSE/HTTP streams: `event: error data: {"message":"Token expired","code":40142,"statusCode":401}` + +## Common Causes + +1. **Natural token expiration** (80% of cases) + - Token has reached its configured Time-To-Live (TTL) + - Long-running sessions exceed token lifetime + - Application doesn't refresh tokens proactively + + +2. **Missing token refresh mechanism** (15% of cases) + - No automatic token renewal implemented + - Token refresh not triggered before expiration + - Error handling doesn't include token refresh + + +3. **Network issues** (5% of cases) + - Connection drops prevent timely token refresh + - Offline periods exceed token lifetime + - Network delays in token renewal requests + + +## Resolution Steps + +1. **Request a new token immediately** + - Call your authentication endpoint or auth callback + - Ensure the new token has an appropriate TTL for your use case + - Verify the token generation process is working correctly + + +2. **Update your Ably client with the new token** + - Replace the expired token in your client configuration + - For realtime connections, the SDK will automatically reconnect with the new token + - For REST clients, update the token in your next request + + +3. **Implement automatic token refresh** + - Set up token renewal when 70-80% of TTL has elapsed + - Use Ably's auth callback mechanism for automatic renewal + - Handle token refresh failures with appropriate retry logic + + +4. **For client-side applications (e.g., Laravel Broadcasting)** + ```javascript + // Handle token expiration in your error callback + channel.error(error => { + if (error && error.code === 40142) { + // Request new token from your backend + refreshAblyToken().then(() => { + // Reconnect with new token + reconnectToAbly(); + }); + } + }); + ``` + + + +## Automatic Handling + +Ably SDKs automatically attempt to renew tokens when they expire if you've configured an auth callback or auth URL. The SDK will: +- Detect token expiration +- Call your auth callback/URL for a new token +- Automatically reconnect with the new token +- Resume normal operation without manual intervention + +If no auth callback is configured, you'll need to manually refresh the token and reinitialize the client. + +## Prevention + +- **Implement proactive token refresh**: Renew tokens when 70-80% of their TTL has elapsed + +- **Configure appropriate TTL**: Balance security needs with refresh frequency +- **Use auth callbacks**: Let Ably SDKs handle token renewal automatically +- **Monitor token health**: Track expiration times and refresh patterns +- **Handle network interruptions**: Queue token refresh attempts during offline periods + +## Long-Running Applications + +For applications that run continuously: +- Set token TTL based on your security requirements (typical: 1-24 hours) +- Implement background token refresh processes +- Handle token expiration gracefully during critical operations +- Use connection state monitoring to detect authentication failures early + + +## Related Resources + +- [Token Authentication documentation](https://ably.com/docs/auth/token) +- [Auth callbacks and token refresh](https://ably.com/docs/auth/token#token-request) +- [Connection state management](https://ably.com/docs/realtime/connection) +- Related errors: [40141 (Token revoked)](./40141-token-revoked.mdx), [40143 (Token unrecognised)](./40143-token-unrecognised.mdx) + +## Need Further Help? + +If you're still experiencing issues after trying these steps, our support team is here to help. + +**Contact Ably Support**: https://ably.com/support + +When contacting support, please provide: +- Your account ID and app ID +- The full error message including error code 40142 +- Steps to reproduce the issue +- Any relevant code snippets (without sensitive credentials) +- The SDK and version you're using + +Our team will help you resolve this issue as quickly as possible. + + + + + + + + + + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/40144-invalid-jwt-token-format.mdx b/src/pages/docs/platform/errors/codes/40144-invalid-jwt-token-format.mdx new file mode 100644 index 0000000000..753ce776d4 --- /dev/null +++ b/src/pages/docs/platform/errors/codes/40144-invalid-jwt-token-format.mdx @@ -0,0 +1,194 @@ + + + + + + + + +# Error 40144: Invalid JWT token format + +## What Happened + +Your JWT token failed validation due to missing required fields, incorrect data types, or unsupported configurations. + +## Quick Reference + +| Error Code | HTTP Status | Category | Retryable | +|------------|-------------|----------|-----------| +| 40144 | 400/401 | Client Error (Authentication) | No - requires fixing token format | + +## Quick Fix + +- Ensure your JWT includes required fields `iat` and `exp` as numeric timestamps +- Check that capability and revocation key fields are not empty strings +- Use supported algorithms (not HS384) and avoid excessive token nesting + +## Error Messages + +You may see one of these messages: +- "Invalid token; iat must be specified" +- "Invalid token; iat must be a number" +- "Invalid token; exp must be specified" +- "Invalid token; exp must be a number" +- "Invalid token request body; capability must not be the empty string" +- "Invalid capability" +- "Invalid token; revocationKey must not be the empty string" +- "Invalid token; revocationKey must be a string" +- "Invalid token; embedded JWT tokens cannot be nested more than once" +- "Invalid embedded access token" +- "HS384 is not supported" + +## Common Causes + +1. **Missing or invalid timestamps** (60% of cases) + + - JWT missing `iat` (issued at) field + - JWT missing `exp` (expires) field + - Timestamps not formatted as numbers (e.g., strings or decimals with microseconds) + + +2. **Library-generated format issues** (25% of cases) + + - PHP Lcobucci/JWT library creating timestamps with microseconds + - JWT libraries producing string timestamps instead of numbers + - Demo token generators with incorrect field types + +3. **Invalid capability or configuration** (10% of cases) + + - Empty capability string when specified + - Empty revocation key when specified + - Unsupported HS384 algorithm + +4. **Token nesting issues** (5% of cases) + + - Embedded JWT tokens nested more than once + - Invalid embedded access tokens + +## Resolution Steps + +1. **Validate your JWT structure** + - Decode your token using [JWT.io](https://jwt.io) or similar tools + - Verify the payload contains required fields + - Check all field data types match requirements + + +2. **Ensure required fields are correct** + Your JWT payload must include: + - `iat`: Unix timestamp as a whole number (e.g., `1234567890`) + - `exp`: Unix timestamp as a whole number (e.g., `1234567890`) + - If using capability: Must be a non-empty string + - If using revocation key: Must be a non-empty string + + +3. **Fix library-specific issues** + + **For PHP Lcobucci/JWT users:** + Configure the library to use integer timestamps only. By default, it creates timestamps with microseconds which Ably rejects. + + + **For Kafka Connect/Confluent integration:** + Add these converter configurations: + - `key.converter: org.apache.kafka.connect.converters.ByteArrayConverter` + - `value.converter: org.apache.kafka.connect.converters.ByteArrayConverter` + - `value.converter.schemas.enable: false` + + +4. **Test with a minimal valid token** + Create a simple token with only required fields to isolate the issue. + See the [Ably JWT authentication documentation](https://ably.com/docs/auth/token) for token structure requirements. + + +5. **Check for unsupported features** + - Don't use HS384 algorithm (use HS256 or RS256 instead) + - Don't nest JWT tokens more than one level deep + - Don't use empty strings for capability or revocation keys + + +## Automatic Handling + +This is a client error that will not be automatically retried. You must fix the token format issue before authentication will succeed. + +## Prevention + +- Use established JWT libraries with proper configuration for integer timestamps +- Validate tokens after generation using JWT debugging tools +- Test your token generation with the specific Ably SDK you're using +- Monitor authentication failures during development to catch format issues early + + +## Related Resources + +- [Ably JWT Authentication Guide](https://ably.com/docs/auth/token) +- [Token Generation Documentation](https://ably.com/docs/auth/token#token-request-process) +- [JWT Specification (RFC 7519)](https://tools.ietf.org/html/rfc7519) +- Related errors: [40140](./40140-token-expired), [40141](./40141-token-unrecognized), [40142](./40142-token-revoked) + +## Need Further Help? + +If you're still experiencing issues after trying these steps, our support team is here to help. + +**Contact Ably Support**: https://ably.com/support + +When contacting support, please provide: +- Your account ID and app ID +- The full error message including error code 40144 +- Steps to reproduce the issue +- Any relevant code snippets (without sensitive credentials) +- The SDK and version you're using + +Our team will help you resolve this issue as quickly as possible. + + + + + + + + + + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/40146-unsupported-token-claims.mdx b/src/pages/docs/platform/errors/codes/40146-unsupported-token-claims.mdx new file mode 100644 index 0000000000..ad5971c617 --- /dev/null +++ b/src/pages/docs/platform/errors/codes/40146-unsupported-token-claims.mdx @@ -0,0 +1,201 @@ + + + + + + + + +# Error 40146: Unsupported Token Claims + +## What Happened + +Your token request to Ably's server includes `userClaims` or `limitsClaims`, which are not supported in server-generated tokens. + +## Quick Reference + +| Error Code | HTTP Status | Category | Retryable | +|------------|-------------|----------|-----------| +| 40146 | 401 | Client Error (Authentication) | No - requires removing unsupported claims or switching to client-side token generation | + +## Quick Fix + +- Remove `userClaims` and `limitsClaims` from your token request +- Use standard token capabilities instead +- Or switch to client-side token generation if you need these features + +## Error Messages + +You'll see this message: +- "userClaims and limitsClaims are not currently supported in server-generated tokens" + +## Common Causes + +1. **Including advanced JWT features in server-side token requests** (most common) + - Adding `userClaims` to your token request body + - Including `limitsClaims` in server-generated token requests + - Attempting to use JWT features only available in client-side generation + + +2. **Migration from custom token generation** + - Moving from client-side to server-side token generation without removing unsupported features + - Copy-pasting token request code that includes these claims + + +3. **Documentation misunderstanding** + - Mixing examples meant for client-side and server-side token generation + - Assuming all JWT features work with server-side generation + + +## Resolution Steps + +### 1. Remove Unsupported Claims + +If these claims aren't essential to your application: + +1. **Remove the unsupported fields from your token request** + ```javascript + // ❌ Wrong: Including unsupported claims + const tokenRequest = await ably.auth.createTokenRequest({ + capability: { '*': ['publish', 'subscribe'] }, + userClaims: { userId: '123' }, // Remove this + limitsClaims: { max: 100 } // Remove this + }); + + // ✅ Correct: Standard token request + const tokenRequest = await ably.auth.createTokenRequest({ + capability: { '*': ['publish', 'subscribe'] } + }); + ``` + + +2. **Use standard token features** + - Use `clientId` for user identification + - Use capabilities for access control + - Store user-specific data in your application + + +### 2. Switch to Client-Side Token Generation + +If you need `userClaims` or `limitsClaims`: + +1. **Generate tokens in your application** + - Use a JWT library in your backend + - Sign tokens with your Ably API key + - Include any JWT claims you need + + +2. **Return signed tokens to clients** + - Your server generates the complete JWT + - Clients use the token directly with Ably + - Full control over all JWT features + +See [Ably's token authentication documentation](https://ably.com/docs/auth/token) for implementation details. + +### 3. Alternative Approaches + +Consider if you actually need these advanced claims: + +1. **Use token capabilities** for fine-grained access control +2. **Use clientId** to identify users +3. **Store user metadata** in your own database +4. **Implement custom authorization** in your application layer + + +## Automatic Handling + +This is a validation error that occurs before token generation. Ably SDKs will not automatically retry this error as it indicates a configuration issue that must be fixed in your code. + +## Prevention + +- **Understand the difference** between server-side and client-side token generation +- **Check feature support** before implementing token generation +- **Test token generation** in development environments +- **Choose the appropriate method** based on your feature requirements + + +## Token Generation Methods Comparison + +### Server-Side Generation (Ably-Managed) +- Simpler implementation +- Standard JWT claims only +- `userClaims` and `limitsClaims` **NOT** supported +- Suitable for basic authentication needs + +### Client-Side Generation (Self-Managed) +- Full JWT specification support +- `userClaims` and `limitsClaims` supported +- More complex implementation +- Complete control over token contents + + +## Related Resources + +- [Token Authentication](https://ably.com/docs/auth/token) +- [Token Request API](https://ably.com/docs/api/rest-api#token-request) +- [JWT Token Claims](https://ably.com/docs/auth/token#claims) +- [Authentication Guide](https://ably.com/docs/auth) +- Related errors: [40001](./40001-bad-request.md) (Invalid token request) + +## Need Further Help? + +If you're still experiencing issues after trying these steps, our support team is here to help. + +**Contact Ably Support**: https://ably.com/support + +When contacting support, please provide: +- Your account ID and app ID +- The full error message including error code 40146 +- Steps to reproduce the issue +- Any relevant code snippets (without sensitive credentials) +- The SDK and version you're using + +Our team will help you resolve this issue as quickly as possible. + + + + + + + + + + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/40149-token-error-range-boundary.mdx b/src/pages/docs/platform/errors/codes/40149-token-error-range-boundary.mdx new file mode 100644 index 0000000000..7c56b21c67 --- /dev/null +++ b/src/pages/docs/platform/errors/codes/40149-token-error-range-boundary.mdx @@ -0,0 +1,159 @@ + + + + + + + + +# Error 40149: Token error range boundary + +## What Happened + +Your authentication token encountered an issue at the boundary of Ably's token error classification range (40140-40149). + +## Quick Reference + +| Error Code | HTTP Status | Category | Retryable | +|------------|-------------|----------|-----------| +| 40149 | 401 | Authentication (Token) | Yes - after token refresh | + +## Quick Fix + +- Refresh your authentication token immediately +- Verify the new token has proper permissions +- Reconnect with the fresh token + +## Error Messages + +You may see error messages similar to: +- "Token error (range 40140-40149)" +- HTTP 401 response with error code 40149 +- Authentication failure at token range boundary + +## Common Causes + +1. **Token validation boundary issue** (Most common) + - Token validation failed at the edge of the error range + - Authentication system classified the error at range boundary + + +2. **SDK error classification** + - SDK identified a token-related authentication failure + - Error fell within the recoverable token error range + + +3. **Token lifecycle event** + - Token expired or became invalid + - Authentication failure requiring token refresh + + +## Resolution Steps + +1. **Identify the specific token issue** + - Check for more detailed error information in your logs + - Look for specific error codes within the 40140-40149 range + - Review the complete authentication context + + +2. **Refresh your authentication token** + - Request a new token from your authentication endpoint + - Ensure the new token has the required capabilities + - Verify token generation is working correctly + + +3. **Reconnect with the new token** + - Close the current connection + - Create a new connection with the fresh token + - Verify successful authentication + + +4. **Implement proper error handling** + - Set up automatic token refresh for errors in the 40140-40149 range + - Monitor authentication failures + - Log token refresh attempts for debugging + + +## Automatic Handling + +Ably SDKs automatically recognize errors in the 40140-40149 range as recoverable token issues and will: +- Attempt to refresh the token if a token callback is configured +- Not treat these as permanent authentication failures +- Allow reconnection once a valid token is obtained + + +## Prevention + +- **Implement token lifecycle management**: Set up automatic token refresh before expiration +- **Monitor token validity**: Track token expiration times and refresh proactively +- **Use token callbacks**: Configure your SDK with a callback that provides fresh tokens +- **Handle the 40140-40149 range**: Implement specific error handling for token errors + +## Related Resources + +- [Token Authentication](https://ably.com/docs/auth/token) +- [Authentication Best Practices](https://ably.com/docs/auth#best-practice) +- [Error Handling Guide](https://ably.com/docs/realtime/usage#error-handling) +- Related errors: [40140](./40140-token-error-range-start.md), [40142](./40142-token-expired.md) + +## Need Further Help? + +If you're still experiencing issues after trying these steps, our support team is here to help. + +**Contact Ably Support**: https://ably.com/support + +When contacting support, please provide: +- Your account ID and app ID +- The full error message including error code 40149 +- Steps to reproduce the issue +- Any relevant code snippets (without sensitive credentials) +- The SDK and version you're using + +Our team will help you resolve this issue as quickly as possible. + + + + + + + + + + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/40160-insufficient-capabilities.mdx b/src/pages/docs/platform/errors/codes/40160-insufficient-capabilities.mdx new file mode 100644 index 0000000000..fed99b77dc --- /dev/null +++ b/src/pages/docs/platform/errors/codes/40160-insufficient-capabilities.mdx @@ -0,0 +1,181 @@ + + + + + + + + +# Error 40160: Insufficient capabilities + +## What Happened + +Your authentication token or API key doesn't have the required permissions to perform the requested operation on this channel. + +## Quick Reference + +| Error Code | HTTP Status | Category | Retryable | +|------------|-------------|----------|-----------| +| 40160 | 401 | Authentication (Capabilities) | No - requires updated capabilities | + +## Quick Fix + +- Check your token has the required capability (`publish`, `subscribe`, or `presence`) for the channel +- Ensure channel names match your token's capability patterns exactly +- Request a new token with the necessary permissions for your operation + +## Error Messages + +You may see one of these messages: +- "operation not permitted with provided capability" +- "Channel denied access based on given capability; channelId = [channel]" +- "Unauthorized to publish messages with privileged extras" +- "Access denied to channel: namespace requires TLS connection" +- "No authentication options provided; need one of: key, authUrl, or authCallback" + +## Common Causes + +1. **Missing channel permissions** (70% of cases) + + - Token lacks `publish`, `subscribe`, or `presence` capabilities for the channel + - Attempting operations on channels outside your token's scope + - Channel name doesn't match any of your token's capability patterns + +2. **Incorrect channel pattern matching** (20% of cases) + + - Wildcard patterns (`*`) don't match actual channel names + - Case sensitivity issues in channel names + - Namespace prefixes not included in capability patterns + +3. **Special privilege requirements** (10% of cases) + + - Publishing messages with privileged extras without `privileged` capability + - Accessing internal channels without privileged keys + - TLS-only namespace accessed without TLS connection + +## Resolution Steps + +1. **Verify your current capabilities** + + - Check the Ably dashboard for your API key's capabilities + - For token authentication, decode your JWT to inspect the capability claim + - Identify which specific capability is missing for your operation + +2. **Update your token capabilities** + + - For token authentication, regenerate with required capabilities: + ```javascript + const tokenRequest = await ably.auth.createTokenRequest({ + capability: { + 'channel-name': ['publish', 'subscribe'], + 'namespace:*': ['subscribe', 'presence'] + } + }); + ``` + + +3. **Fix channel name patterns** + + - Ensure exact match between channel names and capability patterns + - Remember wildcards (`*`) match zero or more characters + - Check for case sensitivity - channel names are case-sensitive + +4. **For privileged operations** + + - Add `privileged` capability for operations with privileged extras: + ```javascript + capability: { + 'privileged:*': ['publish', 'subscribe', 'privileged'] + } + ``` + + +5. **Check TLS connection requirements** + + - Some namespaces require TLS connections + - Ensure your connection uses `https://` or `wss://` protocols + - Update connection configuration to use TLS + +## Automatic Handling + + +Some Ably SDKs automatically handle this error: +- **Laravel Echo**: Detects 40160 and automatically requests an upgraded token with required capabilities +- **Asset Tracking SDK**: Implements automatic token renewal when encountering capability failures +- Other SDKs do not automatically retry as this requires fixing authentication configuration + +## Prevention + + +- **Plan capabilities carefully**: Include all required permissions when creating tokens +- **Use consistent naming**: Establish clear channel naming conventions +- **Test in development**: Verify token capabilities before production deployment +- **Monitor errors**: Track capability-related errors to identify permission gaps + +## Related Resources + +- [Token Capabilities documentation](https://ably.com/docs/auth/capabilities) +- [Authentication guide](https://ably.com/docs/auth) +- [Channel permissions](https://ably.com/docs/realtime/channels#permissions) +- Related errors: [40101](./40101-invalid-api-key.md), [40102](./40102-token-expired.md) + +## Need Further Help? + +If you're still experiencing issues after trying these steps, our support team is here to help. + +**Contact Ably Support**: https://ably.com/support + +When contacting support, please provide: +- Your account ID and app ID +- The full error message including error code 40160 +- Steps to reproduce the issue +- Any relevant code snippets (without sensitive credentials) +- The SDK and version you're using + +Our team will help you resolve this issue as quickly as possible. + + + + + + + + + + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/40161-namespace-requires-identified-clients.mdx b/src/pages/docs/platform/errors/codes/40161-namespace-requires-identified-clients.mdx new file mode 100644 index 0000000000..cdc2f66853 --- /dev/null +++ b/src/pages/docs/platform/errors/codes/40161-namespace-requires-identified-clients.mdx @@ -0,0 +1,171 @@ + + + + + + + + +# Error 40161: Namespace Requires Identified Clients + +## What Happened + +You're trying to access a channel in a namespace that requires identified clients, but your client doesn't have a valid clientId. + +## Quick Reference + +| Error Code | HTTP Status | Category | Retryable | +|------------|-------------|----------|-----------| +| 40161 | 401 | Client Error (Authentication) | No - requires configuration fix | + +## Quick Fix + +- Set a clientId when initializing your Ably client +- Use token authentication with a clientId included +- Verify the namespace actually requires identified clients + +## Error Messages + +You may see one of these messages: +- "Access denied to channel: namespace {namespace} requires identified clients (channelId = {channel})" +- The `{namespace}` shows the namespace that requires identification +- The `{channel}` shows the full channel name you're trying to access + +## Common Causes + +1. **Missing clientId in authentication** (75% of cases) + - Client initialized without clientId parameter + - Anonymous authentication used where identification required + - Token created without clientId field + + +2. **Namespace security configuration** (20% of cases) + - Namespace configured with `identified: true` + - Security policy enforces client identification + - Compliance requirements mandate tracking individual clients + + +3. **SSE connection issues** (5% of cases) + - Server-Sent Events implementation may handle clientId differently + - Known issue with SSE when "Require identification" is enabled + + +## Resolution Steps + +1. **Set clientId in client options** + ```javascript + // ❌ Wrong: No clientId provided + const ably = new Ably.Realtime({ key: 'your-api-key' }); + + // ✅ Correct: Include a unique clientId + const ably = new Ably.Realtime({ + key: 'your-api-key', + clientId: 'unique-user-id' // e.g., 'user:12345' or email + }); + ``` + + +2. **For token authentication: Include clientId in token request** + ```javascript + const tokenRequest = await ably.auth.createTokenRequest({ + clientId: 'unique-user-id', + capability: { '*': ['publish', 'subscribe'] } + }); + ``` + + +3. **Verify namespace configuration** + - Check your [Ably dashboard](https://ably.com/dashboard) → App → Settings → Channel rules + - Look for the namespace your channel belongs to + - Confirm if "Require identification" is enabled + - Consider if this security requirement is necessary for your use case + + +4. **Choose appropriate clientId patterns** + - **User-based**: `user:12345` or `john.doe@example.com` + - **Session-based**: `session:abc123def456` + - **Service-based**: `backend-service-1` or `api-gateway` + - **Anonymous but unique**: `anon:${uuid}` (if you need unique but anonymous) + + +## Automatic Handling + +This is a configuration error that will not be automatically retried. The SDK will not attempt to reconnect until you provide valid client identification. + +## Prevention + +- **Plan namespace security**: Determine which channels need client identification during design +- **Document clientId strategy**: Maintain consistent patterns across your application +- **Test authentication**: Verify all clients work with your namespace requirements +- **Avoid sensitive data**: Never use passwords or tokens as clientIds (they're visible to other clients) + + +## Related Resources + +- [Client identification documentation](https://ably.com/docs/auth/identified-clients) +- [Namespace configuration](https://ably.com/docs/general/channel-rules-namespaces) +- [Authentication guide](https://ably.com/docs/auth) +- Related errors: [40160](./40160-namespace-requires-tls.mdx) (TLS-only namespaces) + +## Need Further Help? + +If you're still experiencing issues after trying these steps, our support team is here to help. + +**Contact Ably Support**: https://ably.com/support + +When contacting support, please provide: +- Your account ID and app ID +- The full error message including error code 40161 +- Steps to reproduce the issue +- Any relevant code snippets (without sensitive credentials) +- The SDK and version you're using + +Our team will help you resolve this issue as quickly as possible. + + + + + + + + + + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/40162-token-revocation-requires-basic-auth.mdx b/src/pages/docs/platform/errors/codes/40162-token-revocation-requires-basic-auth.mdx new file mode 100644 index 0000000000..375a938b60 --- /dev/null +++ b/src/pages/docs/platform/errors/codes/40162-token-revocation-requires-basic-auth.mdx @@ -0,0 +1,146 @@ + + + + + + + + +# Error 40162: Token revocation requires basic authentication + +## What Happened + +You attempted to revoke tokens while authenticated with a token instead of an API key. Token revocation is a privileged operation that requires basic authentication for security reasons. + +## Quick Reference + +| Error Code | HTTP Status | Category | Retryable | +|------------|-------------|----------|-----------| +| 40162 | 401 | Authentication | No - requires using API key authentication | + +## Quick Fix + +- Use API key authentication instead of token authentication for token revocation +- Move token revocation operations to your server-side code with API key access +- Consider if token revocation is necessary - shorter token TTL might be a better solution + +## Error Messages + +You may see one of these messages: +- "Cannot revoke tokens when using token auth" +- "Unable to revoke token except with basic auth, using the key from which the token was issued" + +## Common Causes + +1. **Using token authentication for revocation** (90% of cases) + + - Client authenticated with a token trying to revoke tokens + - Frontend application attempting server-side operations + - JWT-authenticated requests attempting token management + +2. **Architecture issues** (10% of cases) + + - Mixed authentication strategies causing privilege confusion + - Client doesn't have access to the original API key + - Token-authenticated services trying to manage tokens + +## Resolution Steps + +1. **Switch to API key authentication** + + - Ensure your client is initialized with an API key, not a token + - API keys start with your app ID followed by a dot and the key ID + - Only use API key authentication on secure server-side environments + +2. **Move revocation to server-side** + + - Create a server endpoint to handle token revocation + - Use API key authentication on your server + - Have clients request revocation through your server API + +3. **Consider alternatives to revocation** + + - Use shorter token TTL (time-to-live) values + - Implement token refresh patterns instead of revocation + - Design around token expiration rather than explicit revocation + +4. **Verify your authentication method** + - Check if you're using `key:` parameter (API key) or `token:` parameter + - Review your authentication configuration + - Ensure privileged operations use appropriate authentication + +## Automatic Handling + +This is a client error that will not be automatically retried. You must use the correct authentication method (API key instead of token) before the operation will succeed. + +## Prevention + + +- **Separate authentication concerns**: Use API keys for administrative operations and tokens for client operations +- **Design for token expiration**: Use appropriate token TTL values instead of relying on revocation +- **Keep privileged operations server-side**: Never expose API keys to client applications +- **Use capability restrictions**: Grant tokens only the minimum required capabilities + +## Related Resources + +- [Token Revocation Documentation](https://ably.com/docs/auth/revocation) +- [Authentication Methods](https://ably.com/docs/auth) +- [Basic vs Token Authentication](https://ably.com/docs/auth#basic-authentication) +- Related errors: [40101](https://help.ably.io/error/40101), [40102](https://help.ably.io/error/40102), [40103](https://help.ably.io/error/40103) + +## Need Further Help? + +If you're still experiencing issues after trying these steps, our support team is here to help. + +**Contact Ably Support**: https://ably.com/support + +When contacting support, please provide: +- Your account ID and app ID +- The full error message including error code 40162 +- Steps to reproduce the issue +- Any relevant code snippets (without sensitive credentials) +- The SDK and version you're using + +Our team will help you resolve this issue as quickly as possible. + + + + + + + + + + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/40164-api-key-missing-revocable-tokens-attribute.mdx b/src/pages/docs/platform/errors/codes/40164-api-key-missing-revocable-tokens-attribute.mdx new file mode 100644 index 0000000000..b7c44e8449 --- /dev/null +++ b/src/pages/docs/platform/errors/codes/40164-api-key-missing-revocable-tokens-attribute.mdx @@ -0,0 +1,174 @@ + + + + + + + + +# Error 40164: API key missing revocable tokens attribute + +## What Happened + +Your API key doesn't have the required `revocableTokens` attribute needed to revoke tokens. Token revocation is a privileged operation that must be explicitly enabled on API keys. + +## Quick Reference + +| Error Code | HTTP Status | Category | Retryable | +|------------|-------------|----------|-----------| +| 40164 | 401 | Client Error (Authentication) | No - requires API key configuration change | + +## Quick Fix + +- Enable the `revocableTokens` attribute on your API key in the Ably dashboard +- Generate a new API key with revocation capabilities enabled +- Use an existing key that already has the `revocableTokens` attribute + +## Error Messages + +You'll see this message: +- "Can only revoke tokens issued from a key with the revocableTokens attribute set" + +## Common Causes + +1. **API key created without revocation capability** (90% of cases) + - Standard key generation doesn't include revocation by default + - Key was created before token revocation feature was needed + - Automated key creation process missing this attribute + + +2. **Using legacy API keys** (8% of cases) + - Keys created before revocation feature existed + - Keys migrated from older account configurations + + +3. **Feature not available on account plan** (2% of cases) + - Token revocation may require specific account features + - Advanced security features pending enablement + + +## Resolution Steps + +1. **Check your current API key configuration** + - Log into your [Ably dashboard](https://ably.com/dashboard) + - Navigate to your app → "API Keys" tab + - Look for the `revocableTokens` attribute on your key + - Note if the attribute is present and enabled + + +2. **Enable revocation capability on existing key** (if supported) + - Click "Edit" on your API key + - Look for the `revocableTokens` option + - Enable the attribute if available + - Save the configuration changes + - Test token revocation with the updated key + + +3. **Create a new API key with revocation enabled** + - Navigate to "API Keys" → "Create new key" + - Enable the `revocableTokens` attribute during creation + - Set other required capabilities (publish, subscribe, etc.) + - Save the new key credentials securely + - Update your application to use the new key + + +4. **Verify token revocation works** + - Test your token revocation implementation + - Confirm tokens are successfully revoked + - Monitor for any further 40164 errors + + +## Automatic Handling + +This is a configuration error that cannot be automatically resolved. You must update your API key configuration to include the `revocableTokens` attribute before token revocation operations will succeed. + +## Prevention + +To avoid this error in the future: + +- **Plan key capabilities upfront**: Identify all required attributes when creating API keys +- **Use key templates**: Create templates for different use cases with appropriate attributes +- **Document key purposes**: Maintain documentation of which keys have which capabilities +- **Regular audits**: Review API key configurations periodically + + +## Alternative Approaches + +If token revocation isn't available on your account: + +- **Use shorter token TTL**: Configure tokens with brief lifetimes instead of relying on revocation +- **Implement token refresh**: Use regular token renewal patterns +- **Restrict capabilities**: Issue tokens with minimal necessary permissions +- **Application-level sessions**: Manage user sessions without relying on token revocation + + +## Related Resources + +- [Token Authentication documentation](https://ably.com/docs/auth/token) +- [API Key Management](https://ably.com/docs/auth/basic) +- [Authentication capabilities](https://ably.com/docs/auth/capabilities) +- Related errors: [40133](https://help.ably.io/error/40133) (wrong key for revocation), [40121](https://help.ably.io/error/40121) (revocation not enabled) + +## Need Further Help? + +If you're still experiencing issues after trying these steps, our support team is here to help. + +**Contact Ably Support**: https://ably.com/support + +When contacting support, please provide: +- Your account ID and app ID +- The full error message including error code 40164 +- Steps to reproduce the issue +- Any relevant code snippets (without sensitive credentials) +- The SDK and version you're using + +Our team will help you resolve this issue as quickly as possible. + + + + + + + + + + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/40170-auth-callback-error.mdx b/src/pages/docs/platform/errors/codes/40170-auth-callback-error.mdx new file mode 100644 index 0000000000..86cd68fa22 --- /dev/null +++ b/src/pages/docs/platform/errors/codes/40170-auth-callback-error.mdx @@ -0,0 +1,244 @@ + + + + + + + + +# Error 40170: Authentication callback error + +## What Happened + +The authentication callback or authUrl failed to provide a valid token for establishing the connection. + +## Quick Reference + +| Error Code | HTTP Status | Category | Retryable | +|------------|-------------|----------|-----------| +| 40170 | 401 | Client Error (Authentication) | No - requires fixing auth implementation | + +## Quick Fix + +- Check your auth callback returns a valid token string or token request object +- Ensure authUrl responses include proper Content-Type headers +- Verify tokens aren't exceeding size limits or being double-encoded + +## Error Messages + +You may see one of these messages: +- "authUrl response is missing a content-type header" +- "authUrl responded with unacceptable content-type {type}, should be either text/plain, application/jwt or application/json" +- "Token request callback timed out after {timeout} seconds" +- "Token string is empty" +- "Token string exceeded max permitted length (was {length} bytes)" +- "Token was double-encoded; make sure you're not JSON-encoding an already encoded token request or details" +- "Expected token request callback to call back with a token string or token request/details object" +- "auth_callback raised an exception" +- "Token string was literal null/undefined" + +## Common Causes + +1. **Invalid authUrl response headers** (40% of cases) + - Missing Content-Type header + - Using unsupported Content-Type (not text/plain, application/jwt, or application/json) + + +2. **Auth callback implementation errors** (30% of cases) + - Callback returns null, undefined, or empty string + - Callback throws an unhandled exception + - Callback returns wrong data type + - Callback returns literal "null" or "undefined" as string + + +3. **Token size violations** (15% of cases) + - Token exceeds maximum size (64KB for most SDKs, 128KB for Rust) + - Token request object too large when stringified + + +4. **Double-encoding issues** (10% of cases) + - JSON-encoding an already encoded token + - Token starts with '{' when Content-Type isn't application/jwt + + +5. **Timeout issues** (5% of cases) + - Auth callback takes longer than timeout (default 10 seconds) + - Network latency causes authUrl request to timeout + + +## Resolution Steps + +1. **Verify authUrl response headers** + - Ensure your auth endpoint sets a Content-Type header + - Use one of these supported types: + - `text/plain` for token strings + - `application/jwt` for JWT tokens + - `application/json` for token request objects + + +2. **Fix auth callback implementation** + ```javascript + // ❌ Wrong: Returning null or undefined + const authCallback = async (tokenParams) => { + return null; // Will trigger 40170 + }; + + // ❌ Wrong: Returning literal string "null" + const authCallback = async (tokenParams) => { + return "null"; // Will trigger 40170 + }; + + // ✅ Correct: Return valid token string + const authCallback = async (tokenParams) => { + const response = await fetch('/auth/token'); + const data = await response.json(); + return data.token; // Valid token string + }; + + // ✅ Correct: Return token request object + const authCallback = async (tokenParams) => { + return { + keyName: 'your-key-name', + ttl: 3600000, + capability: JSON.stringify({ '*': ['*'] }) + }; + }; + ``` + + +3. **Check token size limits** + - Maximum token size: 64KB (65536 bytes) for most SDKs + - Rust SDK allows up to 128KB + - If your tokens are large, consider reducing the claims or using token requests instead + + +4. **Avoid double-encoding** + ```javascript + // ❌ Wrong: Double-encoding + const tokenRequest = { keyName: 'key', ttl: 3600000 }; + return JSON.stringify(JSON.stringify(tokenRequest)); // Double-encoded! + + // ✅ Correct: Single encoding + return JSON.stringify(tokenRequest); // Properly encoded once + ``` + + +5. **Handle errors properly in callbacks** + ```javascript + const authCallback = async (tokenParams) => { + try { + const response = await fetch('/auth/token'); + if (!response.ok) { + throw new Error(`Auth failed: ${response.status}`); + } + const data = await response.json(); + return data.token; + } catch (error) { + console.error('Auth callback error:', error); + throw error; // Re-throw to trigger proper error handling + } + }; + ``` + + +6. **Configure timeout if needed** + ```javascript + // Increase timeout for slow networks + const ably = new Ably.Realtime({ + authCallback: yourAuthCallback, + realtimeRequestTimeout: 15000 // 15 seconds instead of default 10 + }); + ``` + + +## Automatic Handling + +This is a client error that will not be automatically retried. The SDK cannot recover from auth callback errors without fixing the underlying implementation issue. + +## Prevention + +- **Test auth callbacks thoroughly** before production deployment +- **Validate token format** before returning from callbacks +- **Log auth errors** for debugging (without exposing sensitive data) +- **Monitor auth endpoint performance** to catch timeout issues early +- **Use proper Content-Type headers** in authUrl responses +- **Implement error handling** in auth callbacks + + +## Related Resources + +- [Authentication documentation](https://ably.com/docs/auth) +- [Token authentication](https://ably.com/docs/auth/token) +- [Auth callbacks guide](https://ably.com/docs/auth/token#token-request) +- Related errors: [40101](./40101-invalid-api-key.md), [40102](./40102-token-expired.md) + +## Need Further Help? + +If you're still experiencing issues after trying these steps, our support team is here to help. + +**Contact Ably Support**: https://ably.com/support + +When contacting support, please provide: +- Your account ID and app ID +- The full error message including error code 40170 +- Steps to reproduce the issue +- Any relevant code snippets (without sensitive credentials) +- The SDK and version you're using + +Our team will help you resolve this issue as quickly as possible. + + + + + + + + + + + + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/40171-token-renewal-not-configured.mdx b/src/pages/docs/platform/errors/codes/40171-token-renewal-not-configured.mdx new file mode 100644 index 0000000000..7c8e5d15c8 --- /dev/null +++ b/src/pages/docs/platform/errors/codes/40171-token-renewal-not-configured.mdx @@ -0,0 +1,195 @@ + + + + + + + + +# Error 40171: Token renewal not configured + +## What Happened + +Your token has expired and the client cannot renew it because no renewal mechanism was configured when initializing the SDK. + +## Quick Reference + +| Error Code | HTTP Status | Category | Retryable | +|------------|-------------|----------|-----------| +| 40171 | 401/403 | Authentication (Token) | No - requires client reconfiguration | + +## Quick Fix + +- Reinitialize your client with an API key instead of a static token +- Or add an `authUrl` to enable automatic token renewal +- Or implement an `authCallback` function for custom token renewal + +## Error Messages + +You may see one of these messages: +- "Need a new token, but authOptions does not include any way to request one (no authUrl, authCallback, or key)" +- "The library was initialized with a token without any way to renew the token when it expires" +- "No means to renew the token is provided (either an API key, authCallback or authUrl)" +- "No means provided to renew auth token" + +## Common Causes + +1. **Static token initialization** (90% of cases) + - Client initialized with a token literal + - No authUrl or authCallback configured + - Token expires after TTL (typically 1 hour) + + +2. **Missing auth configuration** (8% of cases) + - Forgot to implement token renewal when migrating from API key auth + - Copy-pasted example code without understanding renewal requirements + + +3. **Token validation issues** (2% of cases) + - Token capability parsing problems + - Malformed token structure + + +## Resolution Steps + +1. **Choose a token renewal method** + + **Option A: Use an API key** (simplest for server-side) + ```javascript + const client = new Ably.Realtime({ + key: 'your-api-key' + }); + ``` + + + **Option B: Configure authUrl** (recommended for client-side) + ```javascript + const client = new Ably.Realtime({ + authUrl: '/auth/token', + authMethod: 'POST' + }); + ``` + + + **Option C: Implement authCallback** (most flexible) + ```javascript + const client = new Ably.Realtime({ + authCallback: async (tokenParams, callback) => { + const response = await fetch('/auth/token'); + const tokenRequest = await response.json(); + callback(null, tokenRequest); + } + }); + ``` + + +2. **Create a new client instance** + - The failed client cannot be recovered + - Dispose of the old client properly + - Initialize a new client with proper auth configuration + + +3. **Verify token renewal works** + - Test that tokens are automatically renewed before expiration + - Monitor connection state for successful renewal + - Check logs for any renewal warnings + +## Automatic Handling + +When this error occurs: +- The connection enters a FAILED state (permanent) +- No automatic reconnection attempts will be made +- Manual intervention is required to create a new client +- This behavior is mandated by specification RSA4a + + +## Prevention + +- **Never use static tokens in production** without a renewal mechanism +- **Always implement token renewal** when using token authentication +- **Test token expiration scenarios** before deployment +- **Monitor for this error** in production logs to catch configuration issues early + + +## Related Resources + +- [Token Authentication documentation](https://ably.com/docs/auth/token) +- [Token Renewal guide](https://ably.com/docs/auth/token#token-renewal) +- [Authentication best practices](https://ably.com/docs/auth#best-practice) +- Related errors: [40140](./40140-token-expired.mdx), [40170](./40170-auth-callback-failed.mdx) + +## Need Further Help? + +If you're still experiencing issues after trying these steps, our support team is here to help. + +**Contact Ably Support**: https://ably.com/support + +When contacting support, please provide: +- Your account ID and app ID +- The full error message including error code 40171 +- Steps to reproduce the issue +- Any relevant code snippets (without sensitive credentials) +- The SDK and version you're using + +Our team will help you resolve this issue as quickly as possible. + + + + + + + + + + + + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/40300-forbidden.mdx b/src/pages/docs/platform/errors/codes/40300-forbidden.mdx new file mode 100644 index 0000000000..57e7eaefb8 --- /dev/null +++ b/src/pages/docs/platform/errors/codes/40300-forbidden.mdx @@ -0,0 +1,206 @@ + + + + + + + + +--- +title: "Error 40300: Forbidden" +description: "Authorization error when request is understood but refused due to insufficient permissions or policy violations" +--- + +# Error 40300: Forbidden + +## What Happened? + +Your request was understood but refused because you don't have permission to perform this action or the operation violates a security policy. + +## Quick Reference + +| Error Code | HTTP Status | Category | Retryable | +|------------|-------------|----------|-----------| +| 40300 | 403 | Client Error (Authorization) | No - requires fixing permissions or configuration | + +## Quick Fix + +- Ensure you're using HTTPS (not HTTP) for Control API requests +- Verify your account is active and not disabled +- Check that your API key has the required permissions for this operation + +## Error Messages + +You may see one of these messages: +- "Forbidden (HTTPS required)" +- "Account [id] disabled" +- "Application [appId] disabled" +- "Rule type unavailable" +- "unable to publish to qualified channel" +- "Disallowed IP address" +- "You need to be sure" (for destructive operations) +- "Forbidden See https://help.ably.io/error/40300" + + + +## Common Causes + +1. **HTTPS not used for Control API** (40% of cases) + - Control API accessed via HTTP instead of HTTPS + - Security policy requires encrypted connections + - Common when migrating from development to production + + +2. **Account or app disabled** (30% of cases) + - Account manually disabled by Ably + - Application has been disabled + - Subscription or billing issues + + +3. **Missing confirmation for destructive operations** (20% of cases) + - Administrative operations require "areYouSure=yes" parameter + - Protects against accidental deletion or modification + - Common with channel, account, or app management operations + + +4. **Insufficient permissions** (10% of cases) + - API key lacks required capabilities + - Feature not available on current plan + - Rule type not enabled for account + + +## Resolution Steps + +### 1. For HTTPS requirement errors + +**Switch to HTTPS for all Control API calls:** +```javascript +// ❌ Wrong: Using HTTP +const response = await fetch('http://control.ably.net/v1/apps'); + +// ✅ Correct: Using HTTPS +const response = await fetch('https://control.ably.net/v1/apps'); +``` + + +### 2. For disabled account/app errors + +1. **Check account status** in your [Ably dashboard](https://ably.com/dashboard) +2. **Verify billing status** - ensure payment methods are up to date +3. **Contact support** if your account shows as disabled without explanation + + +### 3. For missing confirmation parameters + +**Add the required confirmation parameter for destructive operations:** +```javascript +// ❌ Wrong: Missing confirmation +await fetch('https://control.ably.net/v1/apps/appId', { + method: 'DELETE' +}); + +// ✅ Correct: Include confirmation parameter +await fetch('https://control.ably.net/v1/apps/appId?areYouSure=yes', { + method: 'DELETE' +}); +``` + + +### 4. For permission issues + +1. **Review API key capabilities** in your dashboard +2. **Ensure required permissions** are enabled for the operation +3. **Check your account plan** for feature availability +4. **Generate a new key** with appropriate permissions if needed + + +### 5. For IP address restrictions + +If you see "Disallowed IP address": +- Avoid using localhost or private IPs in production rule configurations +- Use publicly accessible URLs for webhooks and integrations +- Check if your IP is blocked due to security policies + + +## Automatic Handling + +This is an authorization error that will not be automatically retried by Ably SDKs. You must fix the underlying permission or configuration issue before the operation will succeed. + +## Prevention + +- **Always use HTTPS** for Control API and production environments +- **Store API keys securely** and rotate them regularly +- **Implement proper permission management** for different environments +- **Add confirmation parameters** to scripts that perform destructive operations +- **Monitor account status** to prevent unexpected disabling + +## Related Resources + +- [API Security documentation](https://ably.com/docs/api/rest-api#security) +- [Control API documentation](https://ably.com/docs/api/control-api) +- [Authentication guide](https://ably.com/docs/auth) +- [Account management](https://ably.com/dashboard) + +## Need Further Help? + +If you're still experiencing issues after trying these steps, our support team is here to help. + +**Contact Ably Support**: https://ably.com/support + +When contacting support, please provide: +- Your account ID and app ID +- The full error message including error code 40300 +- Steps to reproduce the issue +- Any relevant code snippets (without sensitive credentials) +- The SDK and version you're using + +Our team will help you resolve this issue as quickly as possible. + + + + + + + + + + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/40331-placement-constraint-environment.mdx b/src/pages/docs/platform/errors/codes/40331-placement-constraint-environment.mdx new file mode 100644 index 0000000000..c2d4c2db4c --- /dev/null +++ b/src/pages/docs/platform/errors/codes/40331-placement-constraint-environment.mdx @@ -0,0 +1,169 @@ + + + + + + + + +# Error 40331: Placement constraint environment error + +## What Happened + +Your app attempted to connect to an incorrect Ably environment, violating placement constraints configured for your account. + +## Quick Reference + +| Error Code | HTTP Status | Category | Retryable | +|------------|-------------|----------|-----------| +| 40331 | 403 | Client Error (Account Placement) | No - requires configuration fix | + +## Quick Fix + +- Use your dedicated cluster endpoint (e.g., `acme-realtime.ably.io`) not the default endpoint +- Verify your client library is configured with the correct environment settings +- Check with your account administrator for the correct environment configuration + +## Error Messages + +You may see this message: +- "Unable to activate account due to placement constraint (incompatible environment)" + +## Common Causes + +1. **Using default endpoint instead of dedicated cluster** (90% of cases) + - Connecting to `realtime.ably.io` instead of your custom endpoint + - Missing or incorrect environment configuration in client initialization + - Using example code without updating to your environment settings + +2. **Misconfigured client library** (8% of cases) + - Environment parameter not set or set incorrectly + - API key from one environment used with another environment's endpoint + - Development configuration used in production + +3. **DNS or routing issues** (2% of cases) + - DNS not resolving to correct cluster + - Network configuration preventing access to dedicated endpoint + +## Resolution Steps + +1. **Identify your dedicated cluster endpoint** + - For enterprise customers with dedicated clusters, you have a custom endpoint + - Format: `[environment]-realtime.ably.io` (e.g., `acme-realtime.ably.io`) + - Contact your account administrator if you don't know your environment name + + +2. **Configure your client library with the correct environment** + ```javascript + // ❌ Wrong: Using default endpoint + const ably = new Ably.Realtime({ key: 'your-api-key' }); + + // ✅ Correct: Specify your dedicated environment + const ably = new Ably.Realtime({ + key: 'your-api-key', + environment: 'acme' // Your environment name + }); + ``` + + +3. **Verify your configuration across all services** + - Check all client applications are using the correct environment + - Update any hardcoded endpoints in your codebase + - Ensure CI/CD pipelines use correct environment variables + +4. **Test the connection** + ```javascript + ably.connection.on('connected', () => { + console.log('Successfully connected to dedicated cluster'); + }); + + ably.connection.on('failed', (stateChange) => { + console.error('Connection failed:', stateChange.reason); + }); + ``` + + +## Automatic Handling + +This is a configuration error that will not be automatically retried. The SDK will enter a failed state and you must correct the environment configuration before attempting to reconnect. + +## Prevention + +- **Documentation**: Maintain clear documentation of your environment endpoints +- **Environment variables**: Use configuration files or environment variables rather than hardcoding endpoints +- **Code reviews**: Ensure all client initialization code specifies the correct environment +- **Testing**: Verify connections in staging environments before production deployment + +## Related Resources + +- [Authentication documentation](https://ably.com/docs/auth) +- [Connection state management](https://ably.com/docs/realtime/connection) +- Related errors: [40332](./40332-placement-constraint-site.md) (site constraint) + +## Need Further Help? + +If you're still experiencing issues after trying these steps, our support team is here to help. + +**Contact Ably Support**: https://ably.com/support + +When contacting support, please provide: +- Your account ID and app ID +- The full error message including error code 40331 +- Steps to reproduce the issue +- Any relevant code snippets (without sensitive credentials) +- The SDK and version you're using + +Our team will help you resolve this issue as quickly as possible. + + + + + + + + + + + + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/40332-placement-constraint-violation.mdx b/src/pages/docs/platform/errors/codes/40332-placement-constraint-violation.mdx new file mode 100644 index 0000000000..8850fb36b6 --- /dev/null +++ b/src/pages/docs/platform/errors/codes/40332-placement-constraint-violation.mdx @@ -0,0 +1,188 @@ + + + + + + + + +# Error 40332: Placement Constraint Violation + +## What Happened + +Your application cannot connect to Ably because the account is restricted to a specific region or data center that doesn't match your current connection settings. + +## Quick Reference + +| Error Code | HTTP Status | Category | Retryable | +|------------|-------------|----------|-----------| +| 40332 | 403 | Client Error (Placement Constraint) | No - requires configuration fix | + +## Quick Fix + +- Verify you're using the correct regional endpoint for your account +- Check if your account has region-specific constraints (EU, China, APAC) +- Ensure your SDK configuration includes the custom environment provided + +## Error Messages + +You may see this exact message: +- "Unable to activate account due to placement constraint (incompatible site)" + +## Common Causes + +1. **Incorrect endpoint configuration** (80% of cases) + + - Using global endpoint (realtime.ably.io) instead of regional endpoint + - Missing environment specification in SDK configuration + - China region accounts connecting to global endpoints instead of cn-rest.ably.io + +2. **Region mismatch** (15% of cases) + + - Account restricted to EU but connecting without EU environment configuration + - APAC accounts (ap-southeast-*) connecting with global keys + - Cross-region connection attempts with incompatible placement constraints + +3. **Missing custom environment** (5% of cases) + + - Not using the custom environment provided for your regional account + - Using standard API keys instead of region-specific credentials + +## Resolution Steps + +1. **Identify your account's region** + + - Check your account documentation for regional restrictions + - Look for custom environment settings provided when your account was created + - Common regions include: EU, China (CN), APAC (ap-southeast-*) + +2. **Configure the correct endpoint** + + + For standard regions, update your SDK configuration: + ```javascript + // For EU-restricted accounts + const ably = new Ably.Realtime({ + key: 'your-api-key', + environment: 'eu' // Add this line + }); + + // For China region + const ably = new Ably.Realtime({ + key: 'your-api-key', + restHost: 'cn-rest.ably.io', + realtimeHost: 'cn-realtime.ably.io' + }); + ``` + + +3. **Use custom environments for enterprise accounts** + + + If you were provided a custom environment: + ```javascript + const ably = new Ably.Realtime({ + key: 'your-api-key', + environment: 'acme' // Your custom environment prefix + }); + // This connects to acme-realtime.ably.io + ``` + + +4. **Verify your connection** + + - Test the connection with your regional configuration + - Ensure all SDK instances use the same regional settings + - Check that API keys match the regional endpoint + +## Automatic Handling + +This error cannot be automatically retried by Ably SDKs as it indicates a configuration issue that must be fixed before the connection can succeed. The SDK will not attempt reconnection until you update the configuration. + + +## Prevention + +- Store regional configuration in environment variables to ensure consistency +- Document your account's regional constraints for your team +- Use the same configuration across all environments (development, staging, production) +- Test connections immediately after receiving regional account credentials + + +## Related Resources + +- [Regional endpoints documentation](https://ably.com/docs/platform-customization/custom-environments) +- [Authentication documentation](https://ably.com/docs/auth) +- [Connection state management](https://ably.com/docs/realtime/connection) +- Related error: [40331 - Environment-level placement constraint](https://help.ably.io/error/40331) + +## Need Further Help? + +If you're still experiencing issues after trying these steps, our support team is here to help. + +**Contact Ably Support**: https://ably.com/support + +When contacting support, please provide: +- Your account ID and app ID +- The full error message including error code 40332 +- Steps to reproduce the issue +- Any relevant code snippets (without sensitive credentials) +- The SDK and version you're using + +Our team will help you resolve this issue as quickly as possible. + + + + + + + + + + + + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/40400-resource-not-found.mdx b/src/pages/docs/platform/errors/codes/40400-resource-not-found.mdx new file mode 100644 index 0000000000..fc6f7eff41 --- /dev/null +++ b/src/pages/docs/platform/errors/codes/40400-resource-not-found.mdx @@ -0,0 +1,193 @@ + + + + + + + + +# Error 40400: Resource not found + +## What Happened + +The system could not find the resource you requested - typically an API key component, application, rule, device, or other identifier doesn't exist or is no longer available. + +## Quick Reference + +| Error Code | HTTP Status | Category | Retryable | +|------------|-------------|----------|-----------| +| 40400 | 404 | Client Error (Resource) | No - resource must exist first | + +## Quick Fix + +- Double-check your API key for typos - especially missing or extra characters +- Verify you're using the correct environment (production vs sandbox) +- Confirm the resource exists in your [Ably dashboard](https://ably.com/dashboard) + +## Error Messages + +You may see one of these messages: +- "No application found with id {appId}" +- "No such key {keyId}" +- "invalid key parameter" +- "Device with Id '{deviceId}' is not found" +- "rule {ruleId} not found" +- "Unable to locate subscription" +- "No link to the first/current page of results" +- "Message not found" +- "Could not find path: {path}" +- Various resource-specific "not found" messages + +## Common Causes + + + +1. **Invalid API key components** (Most common) + - Missing characters from the app ID (first part before the dot) + - Missing characters from the key ID (part between dot and colon) + - Incorrect API key format (missing colon separator) + - Using a deleted or regenerated key + +2. **Wrong environment or region** + - Using production key in sandbox environment + - Using sandbox key in production + - Incorrect regional endpoint + +3. **Resource has been deleted** + - API key was regenerated or deleted + - Push device registration removed + - Integration rule deleted + - Application removed + +4. **Pagination issues** + - Missing or malformed pagination links + - Empty result sets + - Manually constructed pagination URLs + +5. **System initialization problems** + - Required monitors not available + - Configuration resources missing + - Dependencies not initialized + +## Resolution Steps + + + +1. **Verify your API key structure** + - API keys have the format: `appId.keyId:keySecret` + - Example: `xVLyHw.Ke5A1w:dTfJtg-OP2L8B...` + - The app ID is before the first dot (`xVLyHw`) + - The key ID is between the dot and colon (`Ke5A1w`) + - Ensure no characters are missing from any part + +2. **Check in your Ably dashboard** + - Log into [https://ably.com/dashboard](https://ably.com/dashboard) + - Navigate to your app + - Go to the "API Keys" tab + - Copy the complete key including all three parts + - Verify you're in the correct environment (production/sandbox) + +3. **For device registration errors** + - Confirm the device ID exists in Push Notifications → Devices + - Check if the device was recently unregistered + - Ensure the device registration hasn't expired + +4. **For pagination errors** + - Use the pagination links provided in API responses + - Don't manually construct pagination URLs + - Check if the result set contains any items + +5. **For integration rule errors** + - Navigate to Integrations in your dashboard + - Verify the rule ID exists and is active + - Check if the rule was recently modified or deleted + +## Automatic Handling + + + +This is a client error that will not be automatically retried. The resource must exist before the operation can succeed. SDKs will not attempt to recover from this error as it indicates a permanent issue with the request. + +## Prevention + + + +- Store API keys in environment variables to avoid typos +- Implement proper error handling for 404 responses +- Validate resource IDs before making API calls +- Use the Ably dashboard to manage and verify resources +- Keep track of resource deletions and updates +- Test API keys after regeneration + +## Related Resources + +- [Authentication documentation](https://ably.com/docs/auth) +- [API key management](https://ably.com/docs/auth/basic) +- [Push notifications setup](https://ably.com/docs/push) +- [Integration rules](https://ably.com/docs/general/integrations) +- [Pagination in REST API](https://ably.com/docs/rest/usage#pagination) + +## Need Further Help? + +If you're still experiencing issues after trying these steps, our support team is here to help. + +**Contact Ably Support**: https://ably.com/support + +When contacting support, please provide: +- Your account ID and app ID +- The full error message including error code 40400 +- Steps to reproduce the issue +- Any relevant code snippets (without sensitive credentials) +- The SDK and version you're using + +Our team will help you resolve this issue as quickly as possible. + + + + + + + + + + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/40500-method-not-allowed.mdx b/src/pages/docs/platform/errors/codes/40500-method-not-allowed.mdx new file mode 100644 index 0000000000..61c88be4dc --- /dev/null +++ b/src/pages/docs/platform/errors/codes/40500-method-not-allowed.mdx @@ -0,0 +1,154 @@ + + + + + + + + +# Error 40500: Method Not Allowed + +## What Happened? + +The HTTP method you used (GET, POST, PUT, DELETE, etc.) is not supported for this endpoint. + +## Quick Reference + +| Error Code | HTTP Status | Category | Retryable | +|------------|-------------|----------|-----------| +| 40500 | 405 | Client Error (Request) | No - requires changing HTTP method | + +## Quick Fix + +- Check the API documentation for the correct HTTP method +- For auth callbacks, use only GET or POST +- Change your request to use the supported method + +## Error Messages + +You may see one of these messages: +- "method not allowed" +- "Unsupported method GET" (or POST, PUT, DELETE, etc.) +- HTTP 405 status with error code 40500 + +## Common Causes + +1. **Wrong HTTP method for endpoint** (70% of cases) + + - Using GET on a POST-only endpoint + - Using POST on a GET-only endpoint + - Using PUT or DELETE on endpoints that don't support them + +2. **Authentication callback misconfiguration** (20% of cases) + + - Auth callbacks only support GET or POST methods + - Using PUT, DELETE, or other methods for auth endpoints + +3. **SDK method validation** (10% of cases) + + - Attempting to use methods not supported by the platform + - Custom HTTP methods that aren't in the SDK's allowed list + +## Resolution Steps + +1. **Identify the correct HTTP method** + + - Check the [Ably REST API documentation](https://ably.com/docs/api/rest-api) for endpoint requirements + - Most read operations use GET + - Most write operations use POST + - Auth endpoints typically require POST for token requests + +2. **For authentication callbacks** + + - Ensure your auth callback URL accepts GET or POST only + - Configure your server to handle the appropriate method: + - GET for simple token requests + - POST when sending auth parameters in the body + - See [Authentication documentation](https://ably.com/docs/auth) for callback setup + +3. **Update your request method** + + - Change the HTTP method in your request configuration + - If using an SDK, use the appropriate method call + - For REST API calls, specify the correct verb + +4. **Verify the change** + - Make the request with the corrected method + - Confirm you receive a successful response + - Check that the operation completes as expected + +## Automatic Handling + +Ably SDKs do not automatically retry this error as it indicates an incorrect request configuration that must be fixed. The SDK will validate methods before making requests where possible. + + +## Prevention + +- Always consult the [REST API documentation](https://ably.com/docs/api/rest-api) for endpoint specifications +- Use SDK methods rather than raw HTTP requests where possible +- For auth callbacks, design your endpoint to accept both GET and POST +- Include explicit error handling for 405 responses in your code + +## Related Resources + +- [REST API Reference](https://ably.com/docs/api/rest-api) +- [Authentication Documentation](https://ably.com/docs/auth) +- [Auth Callback Setup](https://ably.com/docs/auth/token#token-request-callback) +- Related errors: [40101](https://ably.com/docs/errors/40101) (Invalid API Key), [40103](https://ably.com/docs/errors/40103) (Invalid Use of Basic Auth) + +## Need Further Help? + +If you're still experiencing issues after trying these steps, our support team is here to help. + +**Contact Ably Support**: https://ably.com/support + +When contacting support, please provide: +- Your account ID and app ID +- The full error message including error code 40500 +- Steps to reproduce the issue +- Any relevant code snippets (without sensitive credentials) +- The SDK and version you're using + +Our team will help you resolve this issue as quickly as possible. + + + + + + + + + + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/40800-request-timeout.mdx b/src/pages/docs/platform/errors/codes/40800-request-timeout.mdx new file mode 100644 index 0000000000..2cc0a2b9d7 --- /dev/null +++ b/src/pages/docs/platform/errors/codes/40800-request-timeout.mdx @@ -0,0 +1,163 @@ + + + + + + + + +# Error 40800: Request timeout + +## What Happened + +Your request to Ably didn't complete within the allowed time limit, resulting in a timeout. + +## Quick Reference + +| Error Code | HTTP Status | Category | Retryable | +|------------|-------------|----------|-----------| +| 40800 | 408 | Client Error (Network) | Yes - temporary network issue | + +## Quick Fix + +- Check your network connectivity to Ably endpoints +- Verify firewall rules aren't blocking connections +- Consider network latency in your region + +## Error Messages + +You may see one of these messages: +- "Request timed out" +- "Unable to ping service; Request timed out" + +## Common Causes + +1. **Network connectivity issues** (60% of cases) + - High network latency between client and Ably + - Intermittent packet loss + - Network congestion + + +2. **Firewall or proxy interference** (25% of cases) + - Corporate firewall blocking WebSocket connections + - Proxy server introducing delays + - DNS resolution timeouts + + +3. **Server processing delays** (15% of cases) + - Temporary server load conditions + - Large payload processing + - Queue system overload + + +## Resolution Steps + +1. **Verify network connectivity** + - Test connectivity to Ably endpoints (rest.ably.io, realtime.ably.io) + - Check for packet loss or high latency using network diagnostic tools + - Ensure your internet connection is stable + + +2. **Review firewall and proxy settings** + - Ensure WebSocket connections are allowed (port 443) + - Verify Ably domains are whitelisted + - Check proxy timeout settings if applicable + + +3. **Adjust timeout configuration (if available)** + - Some SDKs allow configuring timeout values + - Increase timeout for high-latency environments + - Balance between responsiveness and reliability + + +4. **Monitor for patterns** + - Check if timeouts occur at specific times + - Look for correlation with network events + - Track timeout frequency to identify systemic issues + + +## Automatic Handling + +Ably SDKs implement automatic retry logic for timeout errors: +- The SDK will retry the request with appropriate backoff +- Connection recovery mechanisms handle transient network issues +- You don't need to implement manual retry logic for most timeout scenarios + + +## Prevention + +- **Monitor network quality**: Regularly check connection quality to Ably endpoints +- **Configure appropriate timeouts**: Set timeout values based on your network conditions +- **Use connection state listeners**: Monitor connection state to detect issues early +- **Implement fallback strategies**: Have contingency plans for degraded network conditions + + +## Related Resources + +- [Connection state management](https://ably.com/docs/realtime/connection) +- [Network requirements](https://ably.com/docs/best-practice/network-requirements) +- [Ably status page](https://status.ably.com) +- Related errors: [50003](./50003-server-timeout.md) (server timeout), [80002](./80002-connection-suspended.md) (connection suspended) + +## Need Further Help? + +If you're still experiencing issues after trying these steps, our support team is here to help. + +**Contact Ably Support**: https://ably.com/support + +When contacting support, please provide: +- Your account ID and app ID +- The full error message including error code 40800 +- Steps to reproduce the issue +- Any relevant code snippets (without sensitive credentials) +- The SDK and version you're using + +Our team will help you resolve this issue as quickly as possible. + + + + + + + + + + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/42211-message-rejected-before-publish-rule.mdx b/src/pages/docs/platform/errors/codes/42211-message-rejected-before-publish-rule.mdx new file mode 100644 index 0000000000..36ac69f439 --- /dev/null +++ b/src/pages/docs/platform/errors/codes/42211-message-rejected-before-publish-rule.mdx @@ -0,0 +1,169 @@ + + + + + + + + +# Error 42211: Message rejected by before-publish rule + +## What Happened + +Your chat message was blocked by a custom validation rule configured for this chat room. + +## Quick Reference + +| Error Code | HTTP Status | Category | Retryable | +|------------|-------------|----------|-----------| +| 42211 | 422 | Client Error (Chat) | No - message violates room rules | + +## Quick Fix + +- Review your message content for any restrictions +- Check the chat room's configured rules with your development team +- Modify your message to comply with the room's requirements + +## Error Messages + +You may see this message: +- "The message was rejected before publishing by a rule on the chat room" + +## Common Causes + +1. **Content policy violations** (60% of cases) + + - Message contains prohibited words or phrases + - URLs are restricted in this chat room + - Message format doesn't meet requirements + +2. **Business rule violations** (30% of cases) + + - Message exceeds length limits + - User has exceeded rate limits for this room + - Messages are restricted during certain time periods + +3. **Custom filter violations** (10% of cases) + + - Room-specific rules are in place + - Application has custom compliance requirements + - Special policies apply to this chat context + +## Resolution Steps + +1. **Review your message content** + + - Check for any words or patterns that might be restricted + - Verify URLs are allowed if your message contains links + - Ensure message length is within acceptable limits + +2. **Understand the room rules** + + - Contact your development team for room rule documentation + - Check if there are time-based restrictions + - Verify any user-specific limitations + +3. **Modify and retry** + + - Adjust your message to comply with known restrictions + - Remove or modify any flagged content + - Try sending a simplified version of your message + +4. **For developers: Review rule configuration** + + - Verify before-publish rules are configured appropriately + - Consider implementing client-side validation to prevent rejections + - Provide clear user feedback about message requirements + - Document room rules for your team + +## Automatic Handling + +This is a client error that will not be automatically retried. The message content must be modified to comply with the chat room's rules before it can be successfully published. + + +## Prevention + +- **For users**: Familiarize yourself with any chat room guidelines +- **For developers**: + + - Implement client-side pre-validation to catch violations before sending + - Provide clear communication about room rules to users + - Consider progressive validation (warn before rejecting) + - Use informative error messages that explain specific violations + +## Related Resources + +- [Ably Chat documentation](https://ably.com/docs/chat) +- [Ably Chat SDK for Android](https://github.com/ably/ably-chat-kotlin) +- [Ably Chat SDK for iOS](https://github.com/ably/ably-chat-swift) +- Related error: [42213 - Message rejected by moderation](https://ably.com/docs/errors/42213) + +## Need Further Help? + +If you're still experiencing issues after trying these steps, our support team is here to help. + +**Contact Ably Support**: https://ably.com/support + +When contacting support, please provide: +- Your account ID and app ID +- The full error message including error code 42211 +- Steps to reproduce the issue +- Any relevant code snippets (without sensitive credentials) +- The SDK and version you're using + +Our team will help you resolve this issue as quickly as possible. + + + + + + + + + + + + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/42213-message-rejected-by-moderation.mdx b/src/pages/docs/platform/errors/codes/42213-message-rejected-by-moderation.mdx new file mode 100644 index 0000000000..daf81871c7 --- /dev/null +++ b/src/pages/docs/platform/errors/codes/42213-message-rejected-by-moderation.mdx @@ -0,0 +1,172 @@ + + + + + + + + +# Error 42213: Message rejected by moderation + +## What Happened? + +Your chat message was automatically blocked by AI-powered moderation because it violated the room's content policies. + +## Quick Reference + +| Error Code | HTTP Status | Category | Retryable | +|------------|-------------|----------|-----------| +| 42213 | 422 | Chat (Moderation) | No - content must be revised | + +## Quick Fix + +- Review your message for inappropriate content +- Remove any profanity, toxicity, or spam +- Rephrase using appropriate language +- Retry sending the revised message + +## Error Messages + +You'll see this message: +- "The message was rejected before publishing by a moderation rule on the chat room" + +## Common Causes + +1. **Profanity or offensive language** (most common) + - Explicit language or masked profanity + - Offensive terms or slurs + - Inappropriate sexual content + + +2. **Toxic behavior** + - Harassment or bullying + - Threats or aggressive language + - Hate speech or discrimination + + +3. **Spam or repetitive content** + - Excessive repetition + - Commercial spam or promotions + - Link spam or unauthorized URLs + + +4. **Channel-specific policy violations** + - Content inappropriate for the specific room context + - Violations of custom moderation rules + + +## Resolution Steps + +1. **Review your message content** + - Identify potentially problematic language + - Check for any terms that might trigger moderation + - Consider the context and audience of the chat room + + +2. **Revise your message** + - Remove or replace inappropriate language + - Ensure the message is respectful and constructive + - Avoid excessive repetition or promotional content + + +3. **Retry sending** + - Send your revised message + - If still rejected, consider further revision + - Check if you're following room-specific guidelines + + +4. **If legitimate content is being blocked** + - The message may be a false positive + - Try rephrasing in a different way + - Contact the application support team if the issue persists + + +## Automatic Handling + +This error is not automatically retried by Ably SDKs. The message content must be revised before it can be successfully published. The moderation check happens before the message is distributed to other users, protecting the community from inappropriate content. + + +## Prevention + +- **Familiarize yourself with community guidelines** + - Understand the chat room's content policies + - Be aware of language that might trigger moderation + + +- **Write respectfully** + - Use appropriate language for the audience + - Avoid potentially offensive terms + - Be constructive in your communication + + +- **For developers: Provide clear feedback** + - Display user-friendly error messages + - Offer content guidelines to users + - Consider client-side pre-filtering for common violations + + +## Related Resources + +- [Ably Chat Moderation documentation](https://ably.com/docs/chat/moderation) +- [Ably Chat SDK documentation](https://ably.com/docs/chat) +- [Content moderation best practices](https://ably.com/docs/chat/moderation#best-practices) + +## Need Further Help? + +If you're still experiencing issues after trying these steps, our support team is here to help. + +**Contact Ably Support**: https://ably.com/support + +When contacting support, please provide: +- Your account ID and app ID +- The full error message including error code 42213 +- Steps to reproduce the issue +- Any relevant code snippets (without sensitive credentials) +- The SDK and version you're using + +Our team will help you resolve this issue as quickly as possible. + + + + + + + + + + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/42922-rate-limit-too-many-requests.mdx b/src/pages/docs/platform/errors/codes/42922-rate-limit-too-many-requests.mdx new file mode 100644 index 0000000000..31044d3060 --- /dev/null +++ b/src/pages/docs/platform/errors/codes/42922-rate-limit-too-many-requests.mdx @@ -0,0 +1,184 @@ + + + + + + + + +# Error 42922: Rate limit exceeded - too many requests + +## What Happened + +Your application exceeded the rate limit for external service requests, causing Ably to temporarily reject your request to protect system resources and ensure fair usage. + +## Quick Reference + +| Error Code | HTTP Status | Category | Retryable | +|------------|-------------|----------|-----------| +| 42922 | 429 | Rate Limit (External Services) | Yes - with exponential backoff | + +## Quick Fix + +- Wait before retrying - check the `Retry-After` header if present +- Implement exponential backoff starting at 1 second +- Monitor rate limit headers to avoid hitting limits + +## Error Messages + +You may see one of these messages: +- "rate limit exceeded too many requests" +- "moderation endpoint returned rate limit error" +- "lambda returned rate limit error" +- Dynamic messages from AWS TooManyRequestsException + +## Common Causes + +1. **High message volume through moderation** (60% of cases) + - Burst of chat messages requiring moderation + - Spam attack triggering multiple moderation checks + - Popular live event generating excessive traffic + + +2. **Lambda function rate limiting** (25% of cases) + - Too many concurrent Lambda invocations + - AWS account Lambda limits reached + - Lambda function throttling + + +3. **Account quota exceeded** (15% of cases) + - Moderation quota limit reached for your plan + - Trial account restrictions + - Monthly limits exhausted + + +## Resolution Steps + +1. **Implement exponential backoff** + + ```javascript + let delay = 1000; // Start with 1 second + const maxDelay = 32000; // Cap at 32 seconds + + async function retryWithBackoff(operation, maxRetries = 5) { + for (let i = 0; i < maxRetries; i++) { + try { + return await operation(); + } catch (error) { + if (error.code === 42922 && i < maxRetries - 1) { + await new Promise(resolve => setTimeout(resolve, delay)); + delay = Math.min(delay * 2, maxDelay); // Double delay, cap at max + } else { + throw error; + } + } + } + } + ``` + + +2. **Check rate limit headers** + Monitor response headers to track your usage: + - `X-RateLimit-Limit`: Your rate limit + - `X-RateLimit-Remaining`: Requests remaining + - `X-RateLimit-Reset`: When the limit resets + - `Retry-After`: Suggested wait time (if present) + + +3. **Optimize request patterns** + - Batch operations where possible + - Implement client-side filtering to reduce moderation calls + - Cache frequently accessed Lambda results + - Distribute load across time windows + + +4. **Consider plan upgrade** + If you consistently hit rate limits: + - Review your current plan limits + - Contact sales for higher quotas + - Consider dedicated infrastructure options + + +## Automatic Handling + +This is a rate limit error that requires exponential backoff for retry. Ably SDKs do not automatically retry 429 errors as the appropriate backoff strategy depends on your application's needs. You must implement your own retry logic with exponential backoff. + + +## Prevention + +- **Pre-filter content client-side**: Reduce unnecessary moderation calls by filtering obvious violations locally +- **Implement request queuing**: Buffer and throttle requests during high-traffic periods +- **Monitor usage patterns**: Track your rate limit consumption to predict and prevent hitting limits +- **Use webhooks for async processing**: Instead of synchronous Lambda calls, consider webhook-based patterns + + +## Related Resources + +- [Ably Rate Limits Documentation](https://ably.com/docs/general/limits) +- [Moderation Documentation](https://ably.com/docs/chat/moderation) +- [Integrations Guide](https://ably.com/docs/general/integrations) +- Related errors: [42910](./42910-rate-limit-exceeded.md) (non-fatal rate limit), [42920](./42920-rate-limit-fatal.md) (fatal rate limit) + +## Need Further Help? + +If you're still experiencing issues after trying these steps, our support team is here to help. + +**Contact Ably Support**: https://ably.com/support + +When contacting support, please provide: +- Your account ID and app ID +- The full error message including error code 42922 +- Steps to reproduce the issue +- Any relevant code snippets (without sensitive credentials) +- The SDK and version you're using + +Our team will help you resolve this issue as quickly as possible. + + + + + + + + + + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/49900-call-cancelled.mdx b/src/pages/docs/platform/errors/codes/49900-call-cancelled.mdx new file mode 100644 index 0000000000..2064826a85 --- /dev/null +++ b/src/pages/docs/platform/errors/codes/49900-call-cancelled.mdx @@ -0,0 +1,161 @@ + + + + + + + + +# Error 49900: Call cancelled + +## What Happened + +A request was cancelled before it could complete, typically due to the client closing the connection or explicitly cancelling the operation. + +## Quick Reference + +| Error Code | HTTP Status | Category | Retryable | +|------------|-------------|----------|-----------| +| 49900 | 499 | Client Cancellation | Yes - if the operation is still needed | + +## Quick Fix + +- This is usually expected behavior when operations are cancelled +- If unintentional, check for client timeouts or network interruptions +- Retry the operation if it's still needed + +## Error Messages + +You may see this message: +- "Call cancelled" + +## Common Causes + +1. **Client-initiated cancellation** (most common) + - User navigated away from the page + - Application explicitly cancelled the request + - SDK cleanup during shutdown + + +2. **Client timeout** + - Request exceeded client-side timeout settings + - Network interruption caused timeout + - Connection lost before operation completed + + +3. **Application lifecycle events** + - App was backgrounded or suspended + - Browser tab was closed + - Application shutdown initiated + + +## Resolution Steps + +1. **Determine if the cancellation was intentional** + - Check if the user initiated the cancellation + - Verify if the application is shutting down gracefully + - Review client timeout settings + + +2. **For unintentional cancellations** + - Review and adjust client timeout settings if too aggressive + - Check network stability + - Ensure proper error handling for connection interruptions + + +3. **For application lifecycle issues** + - Implement proper cleanup in your application shutdown handlers + - Save state before operations that might be interrupted + - Consider using background tasks for critical operations + + +## Automatic Handling + +This error represents expected behavior when clients cancel operations. The Ably SDK will: +- Clean up resources automatically +- Not retry cancelled operations (as they were intentionally cancelled) +- Allow you to retry manually if the operation is still needed + + +## Prevention + +- Design your application to handle cancellations gracefully +- Implement proper cleanup in error handlers +- Consider whether operations need to complete even if the user navigates away +- Use appropriate timeout values for your use case + + +## Related Resources + +- [Connection state management](https://ably.com/docs/connect/states) +- [Error handling best practices](https://ably.com/docs/connect/failures) + +## Need Further Help? + +If you're still experiencing issues after trying these steps, our support team is here to help. + +**Contact Ably Support**: https://ably.com/support + +When contacting support, please provide: +- Your account ID and app ID +- The full error message including error code 49900 +- Steps to reproduce the issue +- Any relevant code snippets (without sensitive credentials) +- The SDK and version you're using + +Our team will help you resolve this issue as quickly as possible. + + + + + + + + + + + + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/50000-internal-server-error.mdx b/src/pages/docs/platform/errors/codes/50000-internal-server-error.mdx new file mode 100644 index 0000000000..5376d2695f --- /dev/null +++ b/src/pages/docs/platform/errors/codes/50000-internal-server-error.mdx @@ -0,0 +1,193 @@ + + + + + + + + +# Error 50000: Internal server error + +## What Happened +An unexpected error occurred within Ably's servers while processing your request. + +## Quick Reference +| Error Code | HTTP Status | Category | Retryable | +|------------|-------------|----------|-----------| +| 50000 | 500 | Server Error | Yes - temporary server issue | + +## Quick Fix +- No immediate action required - Ably SDKs handle retry automatically +- Check [Ably status page](https://status.ably.com) if error persists beyond 2 minutes +- Note the request ID from error details for support if needed + +## Error Messages + +You may see one of these messages: +- "Internal server error" +- "Unknown error" +- "Transport error" +- "Unable to process request" +- Additional context-specific messages depending on the operation + +## Common Causes + +1. **Temporary service disruption** (60% of cases) + - Brief internal processing issues + - Transient connectivity problems between internal services + - Temporary resource constraints + +2. **Database or infrastructure issues** (25% of cases) + - Connection pool exhaustion + - Query timeouts + - Service initialization problems + +3. **Unexpected conditions** (15% of cases) + - Malformed internal responses + - Protocol violations + - Edge cases in request processing + +## Resolution Steps + +1. **For transient errors (most cases)** + - Ably SDKs automatically retry with appropriate backoff + - No action required unless error persists beyond 2 minutes + - Monitor your application logs for frequency + +2. **For persistent errors (lasting >2 minutes)** + - Check https://status.ably.com for any ongoing incidents + - Review recent changes to your implementation + - Note the exact error message and any request IDs + + +3. **Gather diagnostic information** + - Record the timestamp of the error + - Note which operation triggered the error + - Check if the error affects all operations or specific ones + - Monitor if error rate is increasing + +## Automatic Handling + +Ably SDKs automatically retry server errors with exponential backoff. The SDK will: +- Retry the operation with increasing delays +- Continue retrying for transient failures +- Maintain connection state during retries +- Queue messages when appropriate (for publish operations) + +Manual retry logic is not needed - let the SDK handle recovery. + + +## Code Examples + +### Monitoring for persistent errors + +```javascript +// Monitor connection state for persistent issues +ably.connection.on('failed', (stateChange) => { + if (stateChange.reason?.code === 50000) { + console.error('Persistent server error:', stateChange.reason); + // Log to your monitoring system + // Check https://status.ably.com + } +}); + +// Connection will automatically retry - no manual intervention needed +ably.connection.on('connected', () => { + console.log('Recovered from server error'); +}); +``` + + +### Handling in request/response operations + +```javascript +try { + const tokenDetails = await ably.auth.requestToken(); +} catch (err) { + if (err.code === 50000) { + // Server error - will be retried automatically by SDK + console.error('Server error during token request:', err.message); + // The SDK will handle retry - just log for monitoring + } +} +``` + + +## Performance Impact + +This error may cause: +- Temporary delays in message delivery +- Brief connection interruptions +- Queuing of outbound messages (automatically handled) +- Possible presence state updates after recovery + +The SDK handles recovery transparently, minimizing impact on your application. + +## Related Resources +- [Ably system status](https://status.ably.com) +- [Connection state management](https://ably.com/docs/realtime/connection) +- [Error handling guide](https://ably.com/docs/best-practice/error-handling) +- [Platform reliability](https://ably.com/four-pillars-of-dependability) + +## Need Further Help? + +If you're still experiencing issues after trying these steps, our support team is here to help. + +**Contact Ably Support**: https://ably.com/support + +When contacting support, please provide: +- Your account ID and app ID +- The full error message including error code 50000 +- Steps to reproduce the issue +- Any relevant code snippets (without sensitive credentials) +- The SDK and version you're using + +Our team will help you resolve this issue as quickly as possible. + + + + + + + + + + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/50001-internal-channel-error.mdx b/src/pages/docs/platform/errors/codes/50001-internal-channel-error.mdx new file mode 100644 index 0000000000..83f155fcca --- /dev/null +++ b/src/pages/docs/platform/errors/codes/50001-internal-channel-error.mdx @@ -0,0 +1,190 @@ + + + + + + + + +# Error 50001: Internal Channel Error + +## What Happened + +The channel encountered an internal error and cannot process your request. This typically indicates a temporary issue with channel operations or message processing. + +## Quick Reference + +| Error Code | HTTP Status | Category | Retryable | +|------------|-------------|----------|-----------| +| 50001 | 500 | Server Error (Channel) | Yes - temporary server issue | + +## Quick Fix + +- No immediate action required - Ably SDKs handle retry automatically +- If persistent (>2 minutes), detach and reattach the channel +- Check [Ably status page](https://status.ably.com) for any ongoing issues + +## Error Messages + +You may see one of these messages: +- "Internal channel error" +- "Unable to handle publish (maximum channelclient pending publishes exceeded)" +- "Unable to send message; channel not responding" + +## Common Causes + +1. **Publish queue overflow** (60% of cases) + - Publishing messages faster than the server can process + - Too many pending messages awaiting acknowledgment + - Lack of backpressure handling in your application + + +2. **Channel not responding** (30% of cases) + - Channel process temporarily unavailable + - Communication timeout between client and channel + - Network interruption during message acknowledgment + + +3. **Internal channel state issues** (10% of cases) + - Unexpected channel state during operation + - Temporary server-side processing error + - Recovery process in progress + + +## Resolution Steps + +1. **For transient errors (most cases)** + - Ably SDKs automatically retry with appropriate backoff + - No action required unless persistent for more than 2 minutes + + +2. **For persistent queue overflow errors** + - Implement flow control in your application: + ```javascript + // Wait for publish acknowledgment before sending next batch + await channel.publish('event', data); + ``` + - Reduce your message publishing rate + - Consider batching multiple small messages into fewer larger ones + + +3. **For channel not responding errors** + - Detach and reattach the channel: + ```javascript + await channel.detach(); + await channel.attach(); + ``` + - Verify your connection state is `connected` + - Check network connectivity + + +4. **If errors persist beyond 2 minutes** + - Check https://status.ably.com for service status + - Note the exact error message and timestamp + - Review recent changes to your implementation + + +## Automatic Handling + +Ably SDKs automatically retry server errors with exponential backoff. The SDK will: +- Retry the operation with increasing delays +- Preserve message order during retries +- Notify you if the error becomes permanent + +Manual retry is not needed for transient 50001 errors. + +## Prevention + +- **Implement backpressure handling**: Monitor your publish rate and slow down when needed +- **Use publish callbacks**: Wait for acknowledgment before sending high volumes +- **Monitor channel health**: Subscribe to connection state changes +- **Batch messages**: Combine multiple small messages when possible + + +## Performance Impact + +This error may cause: +- Temporary message delays while retrying +- Increased latency for affected channel operations +- Potential message reordering if not using idempotent publishing + +The connection remains active, and other channels continue to function normally. + +## Related Resources + +- [Channel documentation](https://ably.com/docs/channels) +- [Connection state management](https://ably.com/docs/realtime/connection) +- [Publishing messages](https://ably.com/docs/channels/messages#publish) +- [Chat API documentation](https://ably.com/docs/chat) (if using Ably Chat) + + +## Need Further Help? + +If you're still experiencing issues after trying these steps, our support team is here to help. + +**Contact Ably Support**: https://ably.com/support + +When contacting support, please provide: +- Your account ID and app ID +- The full error message including error code 50001 +- Steps to reproduce the issue +- Any relevant code snippets (without sensitive credentials) +- The SDK and version you're using + +Our team will help you resolve this issue as quickly as possible. + + + + + + + + + + + + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/50002-internal-connection-error.mdx b/src/pages/docs/platform/errors/codes/50002-internal-connection-error.mdx new file mode 100644 index 0000000000..073344c27d --- /dev/null +++ b/src/pages/docs/platform/errors/codes/50002-internal-connection-error.mdx @@ -0,0 +1,159 @@ + + + + + + + + +# Error 50002: Internal connection error + +## What Happened + +Your application encountered an internal connection error preventing it from establishing or maintaining a connection to Ably's servers. + +## Quick Reference + +| Error Code | HTTP Status | Category | Retryable | +|------------|-------------|----------|-----------| +| 50002 | 500 | Server Error (Connection) | Yes - temporary connection issue | + +## Quick Fix + +- No immediate action required - Ably SDKs handle retry automatically +- Check your network connectivity and DNS resolution +- Verify your fallback host configuration if using custom settings + +## Error Messages + +You may see one of these messages: +- "Internal connection error" +- "Internal channel error" +- "Unable to resolve host [hostname]: No address associated with hostname" +- "ClusteredResource unavailable" + +## Common Causes + + + +1. **DNS resolution failures** (70% of cases) + - Unable to resolve Ably hostnames + - Incorrect fallback host configuration + - DNS server issues + +2. **Network routing problems** (20% of cases) + - No route to host + - Firewall blocking connections + - Network connectivity issues + +3. **Internal state issues** (10% of cases) + - Corrupted connection state + - Unexpected protocol violations + - Backend resource temporarily unavailable + +## Resolution Steps + + + +1. **For transient errors (most cases)** + - Ably SDKs automatically retry with exponential backoff + - No action required unless persistent for more than 2 minutes + + +2. **Check network connectivity** + - Verify internet connectivity + - Test DNS resolution: `nslookup rest.ably.io` + - Confirm no firewall blocks to Ably endpoints + +3. **Review fallback host configuration (if customized)** + + - Remove explicit fallbackHosts if not needed + - Verify all custom fallback hosts are valid + - Ensure correct domain syntax without typos + +4. **For persistent errors** + - Check https://status.ably.com for service issues + - Update to the latest SDK version + - Note the full error message and request ID + +## Automatic Handling + +Ably SDKs automatically retry this error with exponential backoff since it has HTTP status 500. The SDK will: +- Attempt reconnection with increasing delays +- Try fallback hosts if configured +- Eventually enter a suspended state if unable to reconnect + +## Prevention + +- Use default Ably configuration unless specific requirements exist +- Keep SDKs updated to latest versions +- Monitor connection state in your application +- Implement connection state change listeners for visibility + +## Related Resources + +- [Connection state management](https://ably.com/docs/realtime/connection) +- [Connection recovery documentation](https://ably.com/docs/connect/states) +- [Fallback host configuration](https://ably.com/docs/best-practice/fallback-hosts) +- [Ably system status](https://status.ably.com) + +## Need Further Help? + +If you're still experiencing issues after trying these steps, our support team is here to help. + +**Contact Ably Support**: https://ably.com/support + +When contacting support, please provide: +- Your account ID and app ID +- The full error message including error code 50002 +- Steps to reproduce the issue +- Any relevant code snippets (without sensitive credentials) +- The SDK and version you're using + +Our team will help you resolve this issue as quickly as possible. + + + + + + + + + + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/50003-timeout-error.mdx b/src/pages/docs/platform/errors/codes/50003-timeout-error.mdx new file mode 100644 index 0000000000..8ae6741a8a --- /dev/null +++ b/src/pages/docs/platform/errors/codes/50003-timeout-error.mdx @@ -0,0 +1,219 @@ + + + + + + + + +# Error 50003: Timeout error + +## What Happened + +An operation timed out before completing, typically due to network issues, temporary service unavailability, or operations exceeding configured time limits. + +## Quick Reference + +| Error Code | HTTP Status | Category | Retryable | +|------------|-------------|----------|-----------| +| 50003 | 500/503/504/408 | Server Error (Timeout) | Yes - temporary timeout condition | + +## Quick Fix + +- For REST SDK users: No action needed - automatic retry is handled +- For Realtime SDK users: Implement application-level retry logic +- Check [Ably status page](https://status.ably.com) if persistent +- Consider increasing timeout values in SDK configuration + +## Error Messages + +You may see one of these messages: +- "Message send timeout expired" +- "Timeout for trying fallback hosts retries. Total elapsed time exceeded the [timeout]ms limit" +- "timed out before attaching channel" +- "timed out before detaching channel" +- "Ping request cancelled due to request timeout" +- "Timeout waiting for ping response" +- "Connection cancelled due to request timeout" +- "Ping failed as connection has changed state to {state}" +- "cURL error: [specific error message]" +- "network timeout" + +The `{state}` shows the current connection state, and `[timeout]` shows the configured timeout duration in milliseconds. + +## Common Causes + +1. **Network connectivity issues** (40% of cases) + + - High network latency + - Packet loss + - Intermittent connectivity + - Network unreachability + +2. **Message acknowledgment timeout** (30% of cases) + + - Messages not acknowledged within 30 seconds + - RPC communication failures between services + - Server processing delays + +3. **Channel operation timeout** (15% of cases) + + - Channel attach taking too long + - Channel detach not completing + - State transition delays + +4. **Configuration issues** (10% of cases) + + - Timeout values set too low for network conditions + - Insufficient `realtimeRequestTimeout` setting + - Low `httpMaxRetryDuration` for fallback hosts + +5. **Temporary service issues** (5% of cases) + + - Service temporarily unavailable (503) + - High server load + - Infrastructure problems + +## Resolution Steps + +1. **Check SDK type and retry behavior** + + - **REST SDK**: Automatically retries - no action needed + - **Realtime SDK**: Does NOT auto-retry to avoid duplicate messages - implement application-level retry + +2. **For Realtime SDK users - implement retry logic** + ```javascript + // Handle timeout errors with application-level retry + channel.publish('message', data, (err) => { + if (err && err.code === 50003) { + // Implement your retry logic here + setTimeout(() => { + channel.publish('message', data); + }, 1000); // Start with 1 second delay + } + }); + ``` + + +3. **Increase timeout configuration** + ```javascript + const ably = new Ably.Realtime({ + key: 'your-api-key', + realtimeRequestTimeout: 45000, // Increase from default 10s to 45s + httpMaxRetryDuration: 30000 // Increase HTTP retry duration + }); + ``` + + +4. **Monitor for patterns** + - Check if timeouts occur at specific times + - Identify if specific operations consistently timeout + - Review network path between client and Ably + +5. **For persistent issues (>2 minutes)** + - Check https://status.ably.com for service status + - Review recent infrastructure or code changes + - Consider regional connectivity issues + +## Automatic Handling + + +- **REST SDK**: Automatically retries with exponential backoff +- **Realtime SDK**: Does NOT automatically retry (by design to prevent duplicate messages) +- **Connection recovery**: SDK attempts reconnection for connection timeouts +- **Fallback hosts**: Automatically tried when primary host times out (ably-js) + +## Prevention + +- Set appropriate timeout values based on your network conditions +- Monitor timeout patterns to identify infrastructure issues +- Use REST SDK for critical message publishing that requires automatic retry +- Implement application-level retry logic when using Realtime SDK +- Consider network optimization and regional deployment + +## Performance Impact + +This error indicates temporary delays but doesn't affect: +- Other channel operations +- Existing subscriptions (unless connection timeout) +- Messages already queued for delivery + +Connection timeouts may cause: +- Brief message delivery delays +- Presence member updates +- Need to re-establish subscriptions + +## Related Resources + +- [Connection state management](https://ably.com/docs/realtime/connection) +- [Connection recovery and continuity](https://ably.com/docs/connect/states) +- [Timeout configuration](https://ably.com/docs/api/realtime-sdk#client-options) +- [Ably status page](https://status.ably.com) +- Related errors: [80014](./80014-connection-timeout.md) (connection-specific timeout), [50000](./50000-internal-error.md) (general server error) + +## Need Further Help? + +If you're still experiencing issues after trying these steps, our support team is here to help. + +**Contact Ably Support**: https://ably.com/support + +When contacting support, please provide: +- Your account ID and app ID +- The full error message including error code 50003 +- Steps to reproduce the issue +- Any relevant code snippets (without sensitive credentials) +- The SDK and version you're using + +Our team will help you resolve this issue as quickly as possible. + + + + + + + + + + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/50004-service-unavailable-capacity-limit.mdx b/src/pages/docs/platform/errors/codes/50004-service-unavailable-capacity-limit.mdx new file mode 100644 index 0000000000..cbc9568181 --- /dev/null +++ b/src/pages/docs/platform/errors/codes/50004-service-unavailable-capacity-limit.mdx @@ -0,0 +1,181 @@ + + + + + + + + +# Error 50004: Service Unavailable (Capacity Limit) + +## What Happened + +Ably's servers temporarily cannot process your request due to capacity limits or gateway timeouts. + +## Quick Reference + +| Error Code | HTTP Status | Category | Retryable | +|------------|-------------|----------|-----------| +| 50004 | 503/504 | Server Error (Rate Limiting) | Yes - with exponential backoff | + +## Quick Fix + +- Wait and retry with exponential backoff starting at 1-2 seconds +- Check [Ably's status page](https://status.ably.com) for any ongoing issues +- Spread your requests over time if sending high volumes + +## Error Messages + +You may see one of these messages: +- "Service Unavailable while processing request (server at capacity limit - please retry with exponential backoff)" +- "Service Unavailable while establishing connection (server connection rate limit exceeded - please retry with exponential backoff)" +- "Service Unavailable while publishing message (server publish rate limit exceeded - please retry with exponential backoff)" +- "Service Unavailable while creating channel (server channel creation rate limit exceeded - please retry with exponential backoff)" +- Gateway timeout responses (HTTP 504) without specific error text + +## Common Causes + +1. **Server capacity limits reached** (80% of cases) + + - High traffic volume exceeding instance capacity + - Server entering protective "siege mode" during overload + - Instance-level rate limiting triggered + +2. **Connection rate limiting** (10% of cases) + + - Too many new connections being established simultaneously + - Connection burst exceeding server limits + +3. **Message publish rate limiting** (5% of cases) + + - Publishing messages too rapidly + - Batch publish operations exceeding rate limits + +4. **Gateway timeouts** (5% of cases) + + - Upstream service timeout (HTTP 504) + - Network or infrastructure delays + +## Resolution Steps + +1. **Implement exponential backoff retry** + + - Start with a 1-2 second delay + - Double the delay for each retry (2s, 4s, 8s, 16s...) + - Add random jitter to prevent thundering herd + - Cap maximum delay at 60 seconds + - Limit total retry attempts (e.g., 5-10 retries) + +2. **Check service status** + + - Visit [Ably's status page](https://status.ably.com) for any reported issues + - Check if the issue is widespread or isolated + +3. **Optimize request patterns** + + - Spread high-volume operations across time periods + - Avoid burst traffic patterns + - Consider implementing client-side rate limiting + - Use batch operations judiciously during peak times + +4. **For persistent issues** + + - Review your usage patterns for optimization opportunities + - Consider upgrading your plan for higher limits + - Contact support with request patterns and timing details + +## Automatic Handling + +Ably SDKs automatically implement exponential backoff for this error. The SDK will: + +- Retry the operation with increasing delays +- Add jitter to prevent synchronized retries +- Eventually fail if the issue persists beyond retry limits + +You don't need to implement your own retry logic unless you're using the REST API directly. + +## Prevention + +- **Rate limiting awareness**: Monitor your request rates and stay within documented limits + +- **Load distribution**: Spread high-volume operations across time +- **Connection pooling**: Reuse connections instead of creating new ones +- **Batch wisely**: Use batch operations but be mindful of size and frequency +- **Monitor patterns**: Track 50004 errors as early capacity warning indicators + +## Related Resources + +- [Ably Rate Limits Documentation](https://ably.com/docs/general/limits) +- [Connection State Management](https://ably.com/docs/realtime/connection) +- [Batch Publishing Guide](https://ably.com/docs/rest/messages#batch) +- [Status Page](https://status.ably.com) + +## Need Further Help? + +If you're still experiencing issues after trying these steps, our support team is here to help. + +**Contact Ably Support**: https://ably.com/support + +When contacting support, please provide: +- Your account ID and app ID +- The full error message including error code 50004 +- Steps to reproduce the issue +- Any relevant code snippets (without sensitive credentials) +- The SDK and version you're using + +Our team will help you resolve this issue as quickly as possible. + + + + + + + + + + + + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/50005-service-lockdown.mdx b/src/pages/docs/platform/errors/codes/50005-service-lockdown.mdx new file mode 100644 index 0000000000..770abdf889 --- /dev/null +++ b/src/pages/docs/platform/errors/codes/50005-service-lockdown.mdx @@ -0,0 +1,150 @@ + + + + + + + + +# Error 50005: Service in lockdown + +## What Happened? + +Ably has temporarily placed one or more services in emergency lockdown mode to protect infrastructure during a critical incident. + +## Quick Reference + +| Error Code | HTTP Status | Category | Retryable | +|------------|-------------|----------|-----------| +| 50005 | 503 | Server Error (Infrastructure) | Yes - but requires incident resolution | + +## Quick Fix + +- Check [Ably status page](https://status.ably.com) for active incidents +- Wait for incident resolution before retrying +- Consider fallback options if time-critical + +## Error Messages + +You may see one of these messages: +- "Service Unavailable (service in lockdown)" +- "Service Unavailable (unable to modify Push data; service in lockdown)" + +## Common Causes + +1. **Active Infrastructure Incident** (90% of cases) + - Operators have activated emergency lockdown + - Protects services during critical issues + - Prevents cascading failures + + +2. **Service-Specific Protection** (10% of cases) + - Database infrastructure protection (Cassandra) + - Authentication service protection (token requests) + - Push notification service protection + + +## Resolution Steps + +1. **Check Ably Status** + - Visit https://status.ably.com + - Look for active incidents or maintenance + - Subscribe to incident updates + + +2. **Monitor and Wait** + - This is an operational decision, not a transient error + - Service will automatically recover when lockdown is lifted + - Typical resolution time varies by incident severity + + +3. **Implement Graceful Degradation** + - Queue non-critical operations for later + - Show appropriate user messaging about temporary unavailability + - Avoid aggressive retry loops that won't succeed + + +## Automatic Handling + +Ably SDKs will not automatically retry this error indefinitely as it indicates an operational lockdown that requires manual intervention to resolve. The SDK may attempt limited retries but will ultimately fail if the lockdown persists. + + +## Prevention + +This error cannot be prevented by client applications as it represents an infrastructure protection mechanism activated by Ably operators during emergencies. Focus on: +- Building resilient applications that handle temporary service unavailability +- Implementing proper error handling and user feedback +- Having fallback strategies for critical operations + +## Related Resources + +- [Ably Status Page](https://status.ably.com) +- [Connection states and recovery](https://ably.com/docs/realtime/connection#connection-state-recovery) +- [Error handling best practices](https://ably.com/docs/best-practice#error-handling) + +## Need Further Help? + +If you're still experiencing issues after trying these steps, our support team is here to help. + +**Contact Ably Support**: https://ably.com/support + +When contacting support, please provide: +- Your account ID and app ID +- The full error message including error code 50005 +- Steps to reproduce the issue +- Any relevant code snippets (without sensitive credentials) +- The SDK and version you're using + +Our team will help you resolve this issue as quickly as possible. + + + + + + + + + + + + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/50010-internal-server-error.mdx b/src/pages/docs/platform/errors/codes/50010-internal-server-error.mdx new file mode 100644 index 0000000000..7d9cf39d75 --- /dev/null +++ b/src/pages/docs/platform/errors/codes/50010-internal-server-error.mdx @@ -0,0 +1,159 @@ + + + + + + + + +# Error 50010: Internal server error + +## What Happened + +Ably's infrastructure encountered an internal error while processing your request. This typically occurs when edge proxy services or resource allocation systems experience unexpected issues. + +## Quick Reference + +| Error Code | HTTP Status | Category | Retryable | +|------------|-------------|----------|-----------| +| 50010 | 500/501 | Server Error (Infrastructure) | Yes - temporary infrastructure issue | + +## Quick Fix + +- SDKs automatically retry this error with appropriate backoff +- Check [Ably status page](https://status.ably.com) if persistent +- No immediate action required unless error persists beyond 2 minutes + +## Error Messages + +You may see one of these messages: +- "Ably's edge proxy service has encountered an unknown internal error whilst processing the request" +- "Unable to place instance compatible with constraints" +- "Client application:{id} unavailable timer expired" +- "Client channel:{id} unavailable timer expired" +- "Client account:{id} unavailable timer expired" + +## Common Causes + +1. **Edge proxy issues** (60% of cases) + + - CloudFront encounters unrecognized error status + - Network routing problems between edge and origin + - Temporary edge server overload + +2. **Resource allocation failures** (30% of cases) + + - Cluster cannot find nodes matching placement constraints + - Resource initialization timeout exceeded + - Insufficient capacity in specific regions + +3. **Infrastructure instability** (10% of cases) + + - Ring stability problems in distributed system + - Core process issues requiring recovery + - Cascading failures during high load + +## Resolution Steps + +1. **For transient errors (most cases)** + - Ably SDKs automatically retry with exponential backoff + - No action required - connection will recover automatically + - Monitor your application logs for resolution confirmation + +2. **For persistent errors (>2 minutes)** + + - Check https://status.ably.com for any ongoing incidents + - Review recent changes to your implementation + - Note the exact error message and timing + +3. **If affecting critical operations** + - Implement circuit breaker pattern to prevent cascading failures + - Consider temporary fallback mechanisms + - Collect diagnostic information for support + +## Automatic Handling + +Ably SDKs automatically handle this error by: +- Retrying with exponential backoff (starting at 1 second) +- Attempting connection to alternative datacenters +- Preserving message queue during recovery +- Restoring channel attachments after reconnection + +The SDK will continue retry attempts until the connection is restored or enters a terminal state after extended failure. + +## Prevention + +While this is primarily an infrastructure error, you can minimize impact by: +- Using multiple Ably apps across different regions for critical services +- Implementing proper error handling and fallback mechanisms +- Monitoring connection state changes in your application +- Setting appropriate timeout values for critical operations + +## Related Resources + +- [Connection state recovery](https://ably.com/docs/realtime/connection#connection-state-recovery) +- [Error handling best practices](https://ably.com/docs/best-practice#error-handling) +- [Ably status page](https://status.ably.com) +- Related errors: [50000](./50000-internal-error.md), [50003](./50003-timeout-error.md) + +## Need Further Help? + +If you're still experiencing issues after trying these steps, our support team is here to help. + +**Contact Ably Support**: https://ably.com/support + +When contacting support, please provide: +- Your account ID and app ID +- The full error message including error code 50010 +- Steps to reproduce the issue +- Any relevant code snippets (without sensitive credentials) +- The SDK and version you're using + +Our team will help you resolve this issue as quickly as possible. + + + + + + + + + + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/50210-bad-gateway.mdx b/src/pages/docs/platform/errors/codes/50210-bad-gateway.mdx new file mode 100644 index 0000000000..a437ffc6b3 --- /dev/null +++ b/src/pages/docs/platform/errors/codes/50210-bad-gateway.mdx @@ -0,0 +1,157 @@ + + + + + + + + +# Error 50210: Bad Gateway + +## What Happened + +Ably's edge proxy service received an invalid response from the upstream Ably platform servers when attempting to process your request. + +## Quick Reference + +| Error Code | HTTP Status | Category | Retryable | +|------------|-------------|----------|-----------| +| 50210 | 502 | Server Error (Edge Proxy) | Yes - temporary infrastructure issue | + +## Quick Fix + +- No immediate action required - Ably SDKs handle retry automatically +- Check [Ably status page](https://status.ably.com) if persistent +- Implement exponential backoff if using REST API directly + +## Error Messages + +You may see this message: +- "Ably's edge proxy service received an invalid (bad gateway) response from the Ably platform" + +## Common Causes + + +1. **Upstream platform issues** (Most common) + - Ably platform servers returning invalid responses during incidents + - Service degradation during high load periods + +2. **Transient network issues** + - Temporary connectivity problems between CloudFront and Ably platform + - Network routing issues between edge locations and core infrastructure + +3. **Regional outages** + - Affecting specific CloudFront edge locations + - Localized infrastructure problems + +## Resolution Steps + +1. **For transient errors (most cases)** + + - Ably SDKs automatically retry with appropriate backoff + - No action required unless error persists for more than 2 minutes + +2. **For persistent errors (>2 minutes)** + - Check https://status.ably.com for platform incidents + - Review recent changes to your implementation + - Note the time and frequency of errors for support + +3. **If using REST API directly** + + - Implement exponential backoff retry logic + - Start with 1 second delay, doubling up to 32 seconds + - Include jitter to avoid thundering herd effect + +4. **For batch operations** + + - Keep track of failed batches for manual replay if needed + - Consider implementing circuit breaker patterns for repeated failures + - Monitor for patterns (time of day, specific operations) + +## Automatic Handling + + +Ably SDKs automatically retry server errors with exponential backoff. However, some older SDK versions may incorrectly wrap this in a 400 error, preventing automatic retry. Ensure you're using a current SDK version for proper error handling. + +## Prevention + +- Use current SDK versions for proper error handling +- Implement monitoring for 50210 errors to detect patterns +- Consider geographic distribution of requests to avoid single edge location issues +- Keep batch sizes reasonable to minimize impact of failures + +## Related Resources + +- [Ably Status Page](https://status.ably.com) - Check for platform incidents +- [Connection State Management](https://ably.com/docs/realtime/connection) - Understanding connection recovery +- Related errors: [50003](./50003-timeout.md) (Timeout), [50310](./50310-service-unavailable.md) (Service Unavailable), [50410](./50410-gateway-timeout.md) (Gateway Timeout) + +## Need Further Help? + +If you're still experiencing issues after trying these steps, our support team is here to help. + +**Contact Ably Support**: https://ably.com/support + +When contacting support, please provide: +- Your account ID and app ID +- The full error message including error code 50210 +- Steps to reproduce the issue +- Any relevant code snippets (without sensitive credentials) +- The SDK and version you're using + +Our team will help you resolve this issue as quickly as possible. + + + + + + + + + + + + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/50300-service-unavailable.mdx b/src/pages/docs/platform/errors/codes/50300-service-unavailable.mdx new file mode 100644 index 0000000000..ff4fd2e00f --- /dev/null +++ b/src/pages/docs/platform/errors/codes/50300-service-unavailable.mdx @@ -0,0 +1,160 @@ + + + + + + + + +# Error 50300: Service Unavailable + +## What Happened +A required service within Ably's infrastructure is temporarily unavailable, preventing your request from being processed. + +## Quick Reference +| Error Code | HTTP Status | Category | Retryable | +|------------|-------------|----------|-----------| +| 50300 | 503 | Server Error (Infrastructure) | Yes - temporary service issue | + +## Quick Fix +- No immediate action required - Ably SDKs handle retry automatically +- Check [Ably status page](https://status.ably.com) if persistent +- Wait 30-60 seconds before manual retry if needed + +## Error Messages + +You may see one of these messages: +- "Service Unavailable" +- "failed to make request: [details]" +- "Active Traffic Management: traffic is being temporarily redirected to a backup service" +- "Ably's routing layer was unable to service this request" + +## Common Causes + +1. **Temporary infrastructure issues** (60% of cases) + - Service maintenance or deployment + - Routing layer temporarily unavailable + - Infrastructure capacity adjustments + + +2. **Moderation service unavailable** (25% of cases) + - External moderation service unreachable + - Network connectivity issues between services + - Moderation service experiencing downtime + + +3. **Active Traffic Management** (15% of cases) + - Emergency traffic redirection to backup clusters + - Planned infrastructure migration + - Regional failover scenarios + + +## Resolution Steps + +1. **For transient errors (most cases)** + - Ably SDKs automatically retry with exponential backoff + - No action required unless persistent for more than 2 minutes + + +2. **For persistent errors (>2 minutes)** + - Check https://status.ably.com for any ongoing incidents + - Review response headers for alternate endpoints: + - `X-Ably-Serverid`: Identifies which router responded + - May include alternate `realtimeHost` or `restHost` during traffic management + - Note any custom error messages that provide specific guidance + + +3. **If using Chat with moderation enabled** + - The error may indicate moderation service issues + - Messages will be queued and retried automatically + - Consider temporarily disabling moderation if time-critical + + +4. **Monitor and verify recovery** + - Errors should resolve within minutes + - If persistent beyond 5 minutes, note the request ID and server ID from headers + + +## Automatic Handling +Ably SDKs automatically retry 503 errors with exponential backoff. The SDK will: +- Retry with increasing delays (starting at ~1 second) +- Continue retrying for up to 2 minutes +- Fall back to alternate endpoints if provided +- Queue messages during temporary disconnections + + +## Prevention + +While 503 errors are typically infrastructure-related and outside your control: +- Implement robust error handling for service unavailability +- Consider implementing circuit breakers for non-critical features +- Monitor for patterns in your application logs +- Subscribe to [Ably status updates](https://status.ably.com) for proactive notifications + +## Related Resources +- [Connection state recovery](https://ably.com/docs/connect/states) +- [Error handling best practices](https://ably.com/docs/best-practice#error-handling) +- [Ably system status](https://status.ably.com) +- Related errors: [50000](./50000-internal-error.md), [50305](./50305-routing-error.md) + +## Need Further Help? + +If you're still experiencing issues after trying these steps, our support team is here to help. + +**Contact Ably Support**: https://ably.com/support + +When contacting support, please provide: +- Your account ID and app ID +- The full error message including error code 50300 +- Steps to reproduce the issue +- Any relevant code snippets (without sensitive credentials) +- The SDK and version you're using + +Our team will help you resolve this issue as quickly as possible. + + + + + + + + + + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/50310-edge-service-unavailable.mdx b/src/pages/docs/platform/errors/codes/50310-edge-service-unavailable.mdx new file mode 100644 index 0000000000..81dfd42222 --- /dev/null +++ b/src/pages/docs/platform/errors/codes/50310-edge-service-unavailable.mdx @@ -0,0 +1,181 @@ + + + + + + + + +# Error 50310: Edge service unavailable + +## What Happened + +Ably's edge proxy service received a service unavailable response from the Ably platform backend. + +## Quick Reference + +| Error Code | HTTP Status | Category | Retryable | +|------------|-------------|----------|-----------| +| 50310 | 503 | Server Error (Edge Proxy) | Yes - temporary platform issue | + +## Quick Fix + +- No immediate action required - Ably SDKs handle retry automatically +- Check [Ably status page](https://status.ably.com) if persistent +- The platform will typically recover within minutes + +## Error Messages + +You may see this message: +- "Ably's edge proxy service received a service unavailable response code from the Ably platform" + +## Common Causes + +1. **Temporary platform unavailability** (most common) + - Brief service disruption + - Platform overload during traffic spikes + - Automatic recovery expected + + +2. **Backend service issues** + - Core Ably services experiencing availability problems + - Usually resolved quickly by automatic failover + + +3. **Network communication issues** + - Temporary network problems between CloudFront edge and Ably platform + - Often transient and self-resolving + + +4. **Planned maintenance** + - Scheduled platform updates + - Check status page for maintenance windows + + +## Resolution Steps + +1. **For transient errors (most cases)** + - Ably SDKs automatically retry with appropriate backoff + - No action required unless persistent + - Wait 30-60 seconds for automatic recovery + + +2. **For persistent errors (>2 minutes)** + - Check https://status.ably.com for platform status + - Look for any reported incidents or maintenance + - Subscribe to status updates if issue is ongoing + + +3. **If during high-volume operations** + - Consider reducing request rate temporarily + - Implement client-side throttling if pushing large volumes + - Spread load over time if possible + + +4. **Monitor and verify recovery** + ```javascript + ably.connection.on('connected', () => { + console.log('Successfully reconnected to Ably'); + }); + + ably.connection.on('failed', (stateChange) => { + console.error('Connection failed:', stateChange.reason); + // Only take action if failure persists + }); + ``` + + +## Automatic Handling + +Ably SDKs automatically retry 503 errors with exponential backoff. The SDK will: +- Retry the request with increasing delays +- Maintain connection state during retries +- Resume normal operation once platform recovers +- No manual intervention needed for transient issues + +## Prevention + +While 503 errors typically indicate platform-side issues beyond your control: +- Implement graceful degradation in your application +- Cache critical data locally when possible +- Monitor connection state to provide user feedback +- Consider implementing offline-first patterns for critical features + +## Related Resources + +- [Ably Status Page](https://status.ably.com) +- [Connection State Management](https://ably.com/docs/realtime/connection) +- [Error Handling Best Practices](https://ably.com/docs/best-practice#error-handling) +- Related errors: [50010](./50010-edge-internal-error.md), [50210](./50210-edge-bad-gateway.md), [50410](./50410-edge-gateway-timeout.md) + +## Need Further Help? + +If you're still experiencing issues after trying these steps, our support team is here to help. + +**Contact Ably Support**: https://ably.com/support + +When contacting support, please provide: +- Your account ID and app ID +- The full error message including error code 50310 +- Steps to reproduce the issue +- Any relevant code snippets (without sensitive credentials) +- The SDK and version you're using + +Our team will help you resolve this issue as quickly as possible. + + + + + + + + + + + + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/50400-gateway-timeout.mdx b/src/pages/docs/platform/errors/codes/50400-gateway-timeout.mdx new file mode 100644 index 0000000000..f295aa431d --- /dev/null +++ b/src/pages/docs/platform/errors/codes/50400-gateway-timeout.mdx @@ -0,0 +1,177 @@ + + + + + + + + +# Error 50400: Gateway Timeout + +## What Happened + +An operation timed out while waiting for a response from Ably's infrastructure or while processing an asynchronous operation. + +## Quick Reference + +| Error Code | HTTP Status | Category | Retryable | +|------------|-------------|----------|-----------| +| 50400 | 504 | Server Error (Timeout) | Yes - temporary timeout | + +## Quick Fix + +- No immediate action required - Ably SDKs handle retry automatically +- Check [Ably status page](https://status.ably.com) if persistent +- Timeout typically resolves within seconds + +## Error Messages + +You may see one of these messages: +- "Timeout expired" +- "timedEmitAsync timeout expired" +- "[Operation name] timeout expired" + +## Common Causes + +1. **Temporary network delays** (60% of cases) + - High network latency between client and Ably + - Transient connectivity issues + - Regional network congestion + + +2. **Infrastructure processing delays** (30% of cases) + - Temporary high load on Ably services + - Database operation delays + - Channel coordination timeouts + + +3. **Long-running operations** (10% of cases) + - Complex channel operations + - Large message processing + - Event listener accumulation + + +## Resolution Steps + +1. **For transient timeouts (most cases)** + - Ably SDKs automatically retry with appropriate backoff + - No action required unless persistent + + +2. **For persistent timeouts (>2 minutes)** + - Check https://status.ably.com for service incidents + - Verify your network connectivity + - Review recent changes to your implementation + + +3. **For specific operations timing out** + - Consider breaking large operations into smaller chunks + - Review timeout configuration in your implementation + - Check for event listener accumulation in your code + + +## Automatic Handling + +Ably SDKs automatically handle this error with: +- Exponential backoff retry strategy +- Connection state recovery within 2 minutes +- Automatic reconnection when service recovers + + +The SDK will continue retrying until the operation succeeds or the connection enters a terminal state. + +## Code Examples + +### Monitoring for Persistent Timeouts +```javascript +// Monitor connection state for persistent issues +ably.connection.on('failed', (stateChange) => { + if (stateChange.reason?.code === 50400) { + console.log('Gateway timeout - check status.ably.com'); + // Implement fallback logic if needed + } +}); + +// Add timeout configuration for critical operations +const channel = ably.channels.get('critical-channel', { + params: { timeout: 10000 } // Increase timeout for critical operations +}); +``` + + +## Performance Impact + +This error may indicate: +- Temporary service degradation in specific regions +- Network path issues between client and Ably +- Resource constraints during peak usage + +The error typically self-resolves within seconds to minutes. + +## Related Resources + +- [Connection state management](https://ably.com/docs/realtime/connection) +- [Ably system status](https://status.ably.com) +- [Network requirements](https://ably.com/docs/best-practice/network-connectivity) +- Related errors: [50000](./50000-internal-server-error.md), [50003](./50003-internal-timeout.md) + +## Need Further Help? + +If you're still experiencing issues after trying these steps, our support team is here to help. + +**Contact Ably Support**: https://ably.com/support + +When contacting support, please provide: +- Your account ID and app ID +- The full error message including error code 50400 +- Steps to reproduce the issue +- Any relevant code snippets (without sensitive credentials) +- The SDK and version you're using + +Our team will help you resolve this issue as quickly as possible. + + + + + + + + + + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/50410-edge-proxy-gateway-timeout.mdx b/src/pages/docs/platform/errors/codes/50410-edge-proxy-gateway-timeout.mdx new file mode 100644 index 0000000000..f1cb5ee320 --- /dev/null +++ b/src/pages/docs/platform/errors/codes/50410-edge-proxy-gateway-timeout.mdx @@ -0,0 +1,171 @@ + + + + + + + + +# Error 50410: Edge proxy gateway timeout + +## What Happened + +Ably's edge proxy service (CloudFront) timed out waiting for a response from the Ably platform within the expected timeframe. + +## Quick Reference + +| Error Code | HTTP Status | Category | Retryable | +|------------|-------------|----------|-----------| +| 50410 | 504 | Server Error (Edge Proxy) | Yes - temporary network or platform issue | + +## Quick Fix + +- Your request will be automatically retried by Ably SDKs with appropriate backoff +- Check [Ably status page](https://status.ably.com) if the error persists beyond 2 minutes +- No immediate action required for isolated occurrences + +## Error Messages + +You may see this message: +- "Ably's edge proxy service timed out waiting for the Ably platform" + +## Common Causes + +1. **Temporary platform load** (60% of cases) + + - Platform service processing delays during high traffic + - Temporary resource constraints in specific regions + +2. **Network connectivity issues** (30% of cases) + + - Transient network problems between edge proxy and platform + - Regional connectivity disruptions + +3. **Rare platform incidents** (10% of cases) + + - Service disruptions affecting request processing + - Regional service degradation + +## Resolution Steps + +1. **For transient errors (most cases)** + + - Ably SDKs automatically retry with exponential backoff + - No manual intervention required unless persistent + +2. **For persistent errors (lasting >2 minutes)** + - Check the [Ably status page](https://status.ably.com) for any ongoing incidents + - Review your recent traffic patterns for unusual spikes + - Note the time and region where errors occurred + +3. **If errors continue after status check** + - Try connecting through a different network path if possible + - Collect error timestamps and request IDs for support + +## Automatic Handling + +Ably SDKs automatically retry 504 gateway timeout errors with exponential backoff. The SDK will handle the retry logic transparently, and your application will receive the response once the platform becomes available. + + +## Code Examples + +Since this is an infrastructure-level error handled automatically by SDKs, no specific code changes are required. The SDKs handle retries transparently: + +```javascript +// SDKs automatically handle 504 errors with retry logic +const ably = new Ably.Realtime({ key: apiKey }); + +// Your normal publishing code - retries happen automatically +channel.publish('update', data, (err) => { + if (err) { + // Only persistent failures reach here after automatic retries + console.error('Failed after retries:', err); + } +}); +``` + + +## Prevention + +While this error is typically caused by infrastructure-level issues outside your direct control, you can minimize impact by: + +- Implementing request batching to reduce the number of individual requests +- Using Ably's regional endpoints if available for your use case +- Monitoring your application's request patterns to avoid sudden traffic spikes + +## Performance Impact + +This error indicates a temporary delay but doesn't affect: +- Existing WebSocket connections (they remain active) +- Messages already in transit +- Other channels or operations + +The error only impacts the specific HTTP request that timed out. + +## Related Resources + +- [Ably Status Page](https://status.ably.com) +- [Connection State Management](https://ably.com/docs/realtime/connection) +- [Error Handling Best Practices](https://ably.com/docs/best-practice#error-handling) +- Related errors: [50003](https://help.ably.io/error/50003) (Client-side timeout), [50210](https://help.ably.io/error/50210) (Bad gateway), [50310](https://help.ably.io/error/50310) (Service unavailable) + +## Need Further Help? + +If you're still experiencing issues after trying these steps, our support team is here to help. + +**Contact Ably Support**: https://ably.com/support + +When contacting support, please provide: +- Your account ID and app ID +- The full error message including error code 50410 +- Steps to reproduce the issue +- Any relevant code snippets (without sensitive credentials) +- The SDK and version you're using + +Our team will help you resolve this issue as quickly as possible. + + + + + + + + + + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/61002-push-activation-clientid-mismatch.mdx b/src/pages/docs/platform/errors/codes/61002-push-activation-clientid-mismatch.mdx new file mode 100644 index 0000000000..18c7400dbc --- /dev/null +++ b/src/pages/docs/platform/errors/codes/61002-push-activation-clientid-mismatch.mdx @@ -0,0 +1,200 @@ + + + + + + + + +# Error 61002: Push activation clientId mismatch + +## What Happened + +Your device was previously registered for push notifications with one user identity, but you're now trying to activate it with a different user identity. + +## Quick Reference + +| Error Code | HTTP Status | Category | Retryable | +|------------|-------------|----------|-----------| +| 61002 | 400 | Client Error (Push Notifications) | No - requires device reset | + +## Quick Fix + +- Reset the device registration before activating with a new clientId +- Use `device.reset()` then reactivate with the new clientId +- Ensure consistent clientId throughout your app lifecycle + +## Error Messages + +You may see one of these messages: +- "Activation failed: present clientId is not compatible with existing device registration" +- "clientId not compatible with local device clientId" +- "Activation failed - client ID mismatch" + +## Common Causes + +1. **User switching** (60% of cases) + - Different user logged into the app + - Multi-user app on same device + - Logout/login with different account + + +2. **Development testing** (25% of cases) + - Switching between test accounts + - Changing authentication during development + - Testing multiple user scenarios + + +3. **Cached device registration** (15% of cases) + - App reinstalled without proper cleanup + - Device registration persisted from previous session + - Migration from one authentication method to another + + +## Resolution Steps + +1. **Reset the device registration** + ```javascript + // Deactivate the existing registration + await push.deactivate(); + + // Reset the device to clear old clientId + await push.device.reset(); + + // Now activate with the new clientId + await push.activate(); + ``` + + +2. **Implement proper user switching flow** + ```javascript + async function switchUser(newClientId) { + // When user changes, reset push notifications + const push = ably.push; + + // Clear existing registration + await push.deactivate(); + await push.device.reset(); + + // Re-authenticate with new clientId + const newAbly = new Ably.Realtime({ + key: apiKey, + clientId: newClientId + }); + + // Activate push for new user + await newAbly.push.activate(); + } + ``` + + +3. **Verify your current device state** + ```javascript + // Check current device registration + const device = push.device; + console.log('Current device clientId:', device.clientId); + console.log('Auth clientId:', ably.auth.clientId); + + // If they don't match, reset is required + if (device.clientId && device.clientId !== ably.auth.clientId) { + await push.device.reset(); + await push.activate(); + } + ``` + + +## Automatic Handling + +This error requires manual intervention - the SDK will not automatically reset device registration as this could result in lost push notifications. You must explicitly call `device.reset()` to clear the previous registration. + + +## Prevention + +- **Consistent clientId**: Use the same clientId throughout the app lifecycle +- **Handle user changes**: Always deactivate and reset device registration when users switch +- **Clear on logout**: Reset push registration when users log out +- **Error recovery**: Catch error 61002 and implement automatic reset flow if appropriate for your use case + + +## Related Resources + +- [Push Notifications documentation](https://ably.com/docs/push) +- [Push activation guide](https://ably.com/docs/push/activate) +- [Authentication and clientId](https://ably.com/docs/auth/identified-clients) +- Related errors: [40012](https://help.ably.io/error/40012) (Invalid client ID), [40102](https://help.ably.io/error/40102) (Incompatible credentials) + +## Need Further Help? + +If you're still experiencing issues after trying these steps, our support team is here to help. + +**Contact Ably Support**: https://ably.com/support + +When contacting support, please provide: +- Your account ID and app ID +- The full error message including error code 61002 +- Steps to reproduce the issue +- Any relevant code snippets (without sensitive credentials) +- The SDK and version you're using + +Our team will help you resolve this issue as quickly as possible. + + + + + + + + + + + + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/65536-not-an-error-code.mdx b/src/pages/docs/platform/errors/codes/65536-not-an-error-code.mdx new file mode 100644 index 0000000000..b1177f935b --- /dev/null +++ b/src/pages/docs/platform/errors/codes/65536-not-an-error-code.mdx @@ -0,0 +1,166 @@ + + + + + + + + +# Error 65536: Not an error code + +## What Happened + +You've reached this page because you saw the number 65536 somewhere in Ably's documentation, logs, or error messages. However, **65536 is not an error code** - it's a configuration constant representing the maximum message size (64KB) allowed by the Ably protocol. + +## Quick Reference + +| Error Code | HTTP Status | Category | Retryable | +|------------|-------------|----------|-----------| +| 65536 | N/A | Not an error code - Configuration constant | N/A | + +## Quick Fix + +- If you're seeing message size errors, look for **error code 40009** instead +- The value 65536 represents the 64KB maximum message size limit +- Check your message size and ensure it's under 64KB (65,536 bytes) + +## Why You Might See This Number + +The number 65536 appears in several contexts within Ably: + +1. **Connection Details**: As `maxMessageSize: 65536` in connection parameters +2. **Error Messages**: When messages exceed 65536 bytes, you'll see error 40009 mentioning this limit +3. **SDK Constants**: As a configuration value in SDK source code +4. **Channel Flags**: As a bitwise flag value (unrelated to message size) + +## Common Causes + +If you're experiencing issues related to the 65536 value: + +1. **Message Too Large** (Most common) + - Your message exceeds the 64KB limit + - You'll receive error code 40009: "Maximum message length exceeded" + +2. **Configuration Inspection** + - You're reviewing connection details + - The value appears as a normal configuration parameter + +3. **SDK Development** + - You're working with Ably SDK source code + - The constant appears in transport defaults + +## Resolution Steps + +### If Your Message Is Too Large + +1. **Check the actual error code** + - Look for error code **40009** in your logs + - The error message will state: "Maximum message length exceeded size was X bytes, limit is 65536 bytes" + +2. **Reduce your message size** + - Keep messages under 64KB (65,536 bytes) + - Consider splitting large messages into smaller chunks + - Use compression if appropriate + +3. **For batch operations** + - Ensure the total size of all batched messages doesn't exceed 64KB + - Split large batches into multiple publish operations + +## The Actual Error for Size Violations + +When a message exceeds 65536 bytes, you'll receive: +- **Error Code**: [40009](https://help.ably.io/error/40009) +- **HTTP Status**: 400 or 413 +- **Message**: "Maximum message length exceeded" + + + + +## Technical Details + +The value 65536 represents: +- **Size**: 64 kilobytes (KB) +- **Calculation**: 2^16 bytes +- **Scope**: Maximum size for a single message's data payload +- **Protocol**: Defined in Ably specification section CD2c +- **Coverage**: Applied consistently across all Ably SDKs + + + +## Related Resources + +- [Error 40009: Maximum message length exceeded](https://help.ably.io/error/40009) +- [Ably Limits documentation](https://ably.com/docs/general/limits) +- [Message size limits](https://faqs.ably.com/message-size-limits) + +## Need Further Help? + +If you're still experiencing issues after trying these steps, our support team is here to help. + +**Contact Ably Support**: https://ably.com/support + +When contacting support, please provide: +- Your account ID and app ID +- The actual error code you're receiving (likely 40009, not 65536) +- Steps to reproduce the issue +- Any relevant code snippets (without sensitive credentials) +- The SDK and version you're using + +Our team will help you resolve this issue as quickly as possible. + + + + + + + + + + + + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/70003-integration-max-concurrency-exceeded.mdx b/src/pages/docs/platform/errors/codes/70003-integration-max-concurrency-exceeded.mdx new file mode 100644 index 0000000000..0892f3c514 --- /dev/null +++ b/src/pages/docs/platform/errors/codes/70003-integration-max-concurrency-exceeded.mdx @@ -0,0 +1,182 @@ + + + + + + + + +# Error 70003: Integration max concurrency exceeded + +## What Happened + +Your Ably integration (webhooks, queues, or functions) cannot process additional messages because too many requests are already being handled concurrently. + +## Quick Reference + +| Error Code | HTTP Status | Category | Retryable | +|------------|-------------|----------|-----------| +| 70003 | 400 | Integration Error | Yes - after pending requests complete | + +## Quick Fix + +- Allow time for pending integration requests to complete before sending more messages +- Review your integration rules to ensure they're not triggering unnecessarily +- Consider implementing message batching to reduce integration load + +## Error Messages + +You may see one of these messages: +- "Maximum number of pending requests exceeded" + + + +## Common Causes + +1. **High-volume message bursts** (70% of cases) + - Sudden spikes in published messages that trigger integration rules + - Multiple messages triggering the same integration simultaneously + - Batch operations that generate many events at once + + +2. **Integration endpoint bottlenecks** (20% of cases) + - Slow webhook response times causing requests to back up + - Downstream service unable to keep up with write volume + - Network latency to integration endpoints + + +3. **Overly broad integration rules** (10% of cases) + - Integration rules matching more messages than intended + - Multiple rules triggering for the same events + - Unfiltered channel patterns causing excessive triggering + + +## Resolution Steps + +1. **Immediate mitigation** + - The integration system will automatically process pending requests + - Messages continue to be delivered to channels normally + - Integration delivery will resume once concurrency drops below the limit + + +2. **Review integration volume** + - Check your dashboard for message rates on channels with integration rules + - Identify which rules are triggering most frequently + - Look for patterns in when error 70003 occurs + + +3. **Optimize integration rules** + - Make channel filters more specific to reduce unnecessary triggering + - Review if all configured integrations are still needed + - Consider combining multiple rules where appropriate + + +4. **Improve endpoint performance** + - Ensure webhook endpoints respond quickly (< 5 seconds recommended) + - Implement asynchronous processing in your endpoints + - Monitor your endpoint response times for bottlenecks + + +5. **Implement traffic management** + - If possible, spread message publishing over time + - Consider using presence or channel state for high-frequency data + - Implement client-side batching where appropriate + + +## Automatic Handling + +The Ably platform automatically manages integration concurrency: +- Pending requests continue to be processed in order +- New requests are queued when the limit is reached +- No messages are lost - only integration delivery is delayed + +## Prevention + +- **Design for scale**: Plan integration rules with expected message volumes in mind +- **Monitor regularly**: Track integration performance metrics in your dashboard +- **Test gradually**: Increase message volumes progressively when deploying new integrations +- **Optimize endpoints**: Ensure integration endpoints can handle expected load + + +## Performance Impact + +When this error occurs: +- Channel message delivery continues normally +- Only integration delivery (webhooks, queues) is affected +- Client connections and subscriptions remain unaffected +- Recovery is automatic once concurrency decreases + +## Related Resources + +- [Ably Integrations documentation](https://ably.com/docs/general/integrations) +- [Webhook best practices](https://ably.com/docs/general/webhooks) +- [Integration rules configuration](https://ably.com/docs/general/integrations#configure) +- Related errors: [70001](https://help.ably.io/error/70001), [70002](https://help.ably.io/error/70002) + +## Need Further Help? + +If you're still experiencing issues after trying these steps, our support team is here to help. + +**Contact Ably Support**: https://ably.com/support + +When contacting support, please provide: +- Your account ID and app ID +- The full error message including error code 70003 +- Steps to reproduce the issue +- Any relevant code snippets (without sensitive credentials) +- The SDK and version you're using + +Our team will help you resolve this issue as quickly as possible. + + + + + + + + + + + + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/70004-integration-invalid-message-content.mdx b/src/pages/docs/platform/errors/codes/70004-integration-invalid-message-content.mdx new file mode 100644 index 0000000000..19984de822 --- /dev/null +++ b/src/pages/docs/platform/errors/codes/70004-integration-invalid-message-content.mdx @@ -0,0 +1,176 @@ + + + + + + + + +# Error 70004: Integration Invalid Message Content + +## What Happened + +The Ably Integration service rejected a message because its contents don't meet the requirements of the destination service (like AWS SQS, webhooks, or functions). + +## Quick Reference + +| Error Code | HTTP Status | Category | Retryable | +|------------|-------------|----------|-----------| +| 70004 | 400 | Client Error (Integration) | No - requires fixing message content | + +## Quick Fix + +- Ensure message body is not empty (AWS SQS requirement) +- Validate message data is properly formatted JSON +- Check message size is within integration limits + +## Error Messages + +You may see: +- "SQS does not allow empty message body." +- General integration content validation failures + +## Common Causes + +1. **Empty message body** (most common with AWS SQS) + - Publishing null or undefined message data + - Missing message content when SQS integration is active + + +2. **Invalid JSON in message data** + - Malformed JSON that cannot be parsed + - Circular references in object data + - Unsupported data types for serialization + + +3. **Message content issues** + - Binary data that cannot be serialized for webhook delivery + - Character encoding problems + - Message size exceeding integration limits + + +## Resolution Steps + +1. **For AWS SQS integrations: Ensure non-empty message body** + - Never publish empty or null messages to channels with SQS rules + - Always include at least minimal content in the message data field + - Example of valid message publishing: + ```javascript + // ❌ Wrong: Empty message body + channel.publish({ name: 'event' }); // No data field + channel.publish('event', null); // Null data + channel.publish('event', ''); // Empty string + + // ✅ Correct: Include message content + channel.publish('event', { content: 'data' }); + channel.publish('event', 'message text'); + ``` + + +2. **Validate message format before publishing** + - Ensure all data is properly serializable + - Test JSON serialization before sending + - Remove circular references from objects + + +3. **Review integration configuration** + - Check the specific requirements of your integration type + - Verify message format expectations for your webhook/queue + - Ensure size limits are not exceeded + + +4. **Test with simple messages** + - Start with basic string messages to verify integration works + - Gradually add complexity to identify problematic content + - Use Ably's message inspector to examine message structure + + +## Automatic Handling + +This is a validation error that will not be automatically retried. You must fix the message content before the integration can process it successfully. + +## Prevention + +- **Input validation**: Always validate message data before publishing +- **Consistent serialization**: Use standard JSON serialization methods +- **Size management**: Keep message payloads within documented limits +- **Type safety**: Ensure data types match integration requirements +- **Character encoding**: Use UTF-8 encoding for all text content + + +## Related Resources + +- [Ably Integrations documentation](https://ably.com/docs/general/integrations) +- [Message format guidelines](https://ably.com/docs/realtime/messages) +- [AWS SQS integration guide](https://ably.com/docs/general/integrations#aws-sqs) + +## Need Further Help? + +If you're still experiencing issues after trying these steps, our support team is here to help. + +**Contact Ably Support**: https://ably.com/support + +When contacting support, please provide: +- Your account ID and app ID +- The full error message including error code 70004 +- Steps to reproduce the issue +- Any relevant code snippets (without sensitive credentials) +- The SDK and version you're using + +Our team will help you resolve this issue as quickly as possible. + + + + + + + + + + + + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/70005-amqp-queue-timeout.mdx b/src/pages/docs/platform/errors/codes/70005-amqp-queue-timeout.mdx new file mode 100644 index 0000000000..582699e882 --- /dev/null +++ b/src/pages/docs/platform/errors/codes/70005-amqp-queue-timeout.mdx @@ -0,0 +1,185 @@ + + + + + + + + +# Error 70005: AMQP queue timeout + +## What Happened + +Ably couldn't deliver a message to your AMQP queue integration because the delivery operation timed out. + +## Quick Reference + +| Error Code | HTTP Status | Category | Retryable | +|------------|-------------|----------|-----------| +| 70005 | 500 | Server Error (Integration) | Yes - temporary integration issue | + +## Quick Fix + +- Check your AMQP broker is responsive and not overloaded +- Verify network connectivity between Ably and your queue +- Monitor queue depth and consumer processing speed + +## Error Messages + +You may see one of these messages: +- "Timeout sending message to queue" + +## Common Causes + +1. **AMQP broker performance issues** (40% of cases) + - High load on the message broker + - Slow message processing + - Resource constraints + + +2. **Network connectivity problems** (30% of cases) + - High latency between Ably and your broker + - Intermittent network issues + - Firewall blocking connections + + +3. **Queue congestion** (20% of cases) + - Target queue is full or backed up + - Insufficient consumer capacity + - Messages accumulating faster than processing + + +4. **Configuration issues** (10% of cases) + - Incorrect integration settings + - Authentication delays + - Wrong queue names or routing keys + + +## Resolution Steps + +1. **Check AMQP broker health** + - Access your AMQP broker management console + - Review broker performance metrics and logs + - Verify CPU, memory, and disk usage are within normal ranges + - Check queue depth and consumer activity + + +2. **Verify network connectivity** + - Test connectivity from Ably's regions to your AMQP endpoint + - Check network latency using monitoring tools + - Review firewall rules and security groups + - Ensure Ably's IPs are whitelisted if required + + +3. **Review integration configuration** + - Navigate to your Ably Dashboard → Integrations + - Verify AMQP connection settings and credentials + - Confirm queue names and routing keys are correct + - Check the configured timeout values + + +4. **Optimize message flow** + - Monitor message size and volume patterns + - Identify peak load times + - Scale your AMQP broker if needed + - Add more consumers to process messages faster + + +5. **Implement resilience measures** + - Configure dead letter queues for failed messages + - Set up appropriate retry policies + - Monitor both Ably integration logs and broker metrics + - Create alerts for queue depth thresholds + + +## Automatic Handling + +Ably's integration service will automatically retry message delivery with backoff. However, persistent timeouts may require manual intervention to resolve the underlying issue. + +## Prevention + +- **Scale appropriately**: Ensure your AMQP broker can handle peak message volumes +- **Monitor proactively**: Set up alerts for queue depth and broker performance +- **Optimize network**: Use brokers in regions close to Ably's infrastructure +- **Plan capacity**: Size your queues and consumers for expected load +- **Keep messages small**: Use compression or batching for large payloads + + +## Related Resources + +- [Ably Integrations documentation](https://ably.com/docs/general/integrations) +- [AMQP queue integration guide](https://ably.com/docs/general/integrations/queues) +- [Integration rule configuration](https://ably.com/docs/general/integrations#configure) +- Related error: [70006](https://help.ably.io/error/70006) (timeout with backpressure) + +## Need Further Help? + +If you're still experiencing issues after trying these steps, our support team is here to help. + +**Contact Ably Support**: https://ably.com/support + +When contacting support, please provide: +- Your account ID and app ID +- The full error message including error code 70005 +- Steps to reproduce the issue +- Any relevant code snippets (without sensitive credentials) +- The SDK and version you're using + +Our team will help you resolve this issue as quickly as possible. + + + + + + + + + + + + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/70006-amqp-backpressure.mdx b/src/pages/docs/platform/errors/codes/70006-amqp-backpressure.mdx new file mode 100644 index 0000000000..a8ae0c53cb --- /dev/null +++ b/src/pages/docs/platform/errors/codes/70006-amqp-backpressure.mdx @@ -0,0 +1,164 @@ + + + + + + + + +# Error 70006: AMQP broker backpressure + +## What Happened + +Your AMQP message broker (like RabbitMQ or Amazon MQ) is temporarily unable to accept new messages because it's operating at capacity. + +## Quick Reference + +| Error Code | HTTP Status | Category | Retryable | +|------------|-------------|----------|-----------| +| 70006 | 400 or 500 | Integration (AMQP/Queue) | Yes - temporary broker capacity issue | + +## Quick Fix + +- Check your AMQP broker's CPU, memory, and disk usage +- Verify message consumers are actively processing queues +- Scale broker resources or add additional broker nodes if at capacity + +## Error Messages + +You may see one of these messages: +- "AMQP channel buffer highwatermark exceeded" +- "Timeout sending message to queue. ampq connection is backpressured" + +## Common Causes + +1. **High message volume** (60% of cases) + - Broker receiving more messages than it can process + - Sudden traffic spikes overwhelming the broker + - Message production exceeding consumer capacity + + +2. **Resource constraints** (25% of cases) + - Broker running low on memory or CPU + - Disk space approaching limits + - Connection pool exhaustion + + +3. **Queue backlog** (15% of cases) + - Target queues full or nearing capacity + - Accumulated unprocessed messages + - Dead consumer connections not releasing messages + + +## Resolution Steps + +1. **Check broker health immediately** + - Access your AMQP broker management console + - Review CPU and memory utilization metrics + - Check active connection count against limits + - Look for error messages in broker logs + + +2. **Verify queue status** + - Check queue depths for excessive messages + - Ensure consumers are connected and processing + - Look for queues approaching memory or message count limits + - Consider purging non-critical queues if necessary + + +3. **Scale resources if needed** + - Add CPU or memory to broker nodes + - Scale horizontally by adding broker cluster nodes + - Increase consumer instances to process messages faster + - Adjust broker configuration limits if appropriate + + +4. **Monitor and wait for recovery** + - Backpressure typically resolves as broker processes queued messages + - Monitor metrics to confirm improvement + - Messages will be retried automatically once capacity is available + + +## Automatic Handling + +Ably's integration service will automatically retry message delivery when the AMQP broker recovers from backpressure. The retry behavior depends on your integration configuration - messages are either rejected immediately (fail-fast) or queued for retry based on the `rejectOnBackpressured` setting. + + +## Prevention + +- **Capacity planning**: Size broker resources based on expected peak message volume +- **Queue management**: Configure queue length limits and implement message TTL +- **Load distribution**: Spread queues across multiple broker nodes +- **Monitoring**: Set up alerts for 80% resource utilization thresholds +- **Consumer scaling**: Ensure consumers can scale to match message production rate + + +## Related Resources + +- [Ably Queue Integration documentation](https://ably.com/docs/general/integrations/queues) +- [Ably Integrations guide](https://ably.com/docs/general/integrations) +- Your AMQP broker's capacity planning documentation + +## Need Further Help? + +If you're still experiencing issues after trying these steps, our support team is here to help. + +**Contact Ably Support**: https://ably.com/support + +When contacting support, please provide: +- Your account ID and app ID +- The full error message including error code 70006 +- Steps to reproduce the issue +- Any relevant code snippets (without sensitive credentials) +- The SDK and version you're using + +Our team will help you resolve this issue as quickly as possible. + + + + + + + + + + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/80000-connection-failed.mdx b/src/pages/docs/platform/errors/codes/80000-connection-failed.mdx new file mode 100644 index 0000000000..5ac1bd93a2 --- /dev/null +++ b/src/pages/docs/platform/errors/codes/80000-connection-failed.mdx @@ -0,0 +1,226 @@ + + + + + + + + +# Error 80000: Connection failed + +## What Happened + +Your application cannot establish a connection to Ably's servers, preventing all realtime functionality from working. + +## Quick Reference + +| Error Code | HTTP Status | Category | Retryable | +|------------|-------------|----------|-----------| +| 80000 | 400-503 | Connection | Yes - automatic retry after 15 seconds | + +## Quick Fix + +- Check your internet connection is working +- Verify your API key is correct and not expired +- Ensure ports 80 and 443 are not blocked by firewalls + +## Error Messages + +You may see one of these messages: +- "Connection failed or disconnected by server" +- "No transports left to try" (JavaScript SDK only) +- "Unable to connect to {url}" (Ruby SDK) +- "connection broken before receiving publishing acknowledgment" (iOS/Cocoa SDK) +- "Error creating Socket Transport" (.NET SDK) +- "Chain validation failed" (Android/SSL issues) + +## Common Causes + +1. **Network connectivity issues** (60% of cases) + - No internet connection + - Corporate firewall blocking WebSocket connections + - Proxy server configuration problems + + +2. **Invalid credentials** (25% of cases) + - Incorrect API key + - Expired authentication token + - Wrong environment (sandbox vs production) + + +3. **SSL/TLS certificate issues** (10% of cases) + - Certificate chain validation failures (especially on Android) + - SSL handshake failures + - Outdated TLS version + + +4. **Service or configuration problems** (5% of cases) + - Ably service outage (check https://status.ably.com) + - Incorrect endpoint URLs + - All transport methods exhausted + + +## Resolution Steps + +1. **Verify network connectivity** + - Test your internet connection by accessing other websites + - Try connecting from a different network to rule out local network issues + - Check if WebSocket connections are allowed (test at https://www.websocket.org/echo.html) + + +2. **Check your API credentials** + - Log into your [Ably dashboard](https://ably.com/dashboard) + - Navigate to your app → "API Keys" tab + - Verify you're using the complete API key (including app ID prefix) + - Ensure the key has appropriate capabilities for your operations + + +3. **Test network access to Ably** + - Verify ports 80 (HTTP) and 443 (HTTPS) are open + - If behind a corporate firewall, check WebSocket connections are allowed + - For proxy environments, ensure proper proxy configuration + + +4. **Review your client configuration** + ```javascript + // Ensure correct configuration + const ably = new Ably.Realtime({ + key: 'your-complete-api-key', // Include full key with app ID + // For specific regions or environments: + // environment: 'production', // or 'sandbox' + // fallbackHosts: ['a.ably-realtime.com', 'b.ably-realtime.com'] + }); + ``` + + +5. **Monitor connection state** + ```javascript + ably.connection.on('failed', (stateChange) => { + console.log('Connection failed:', stateChange.reason); + // The SDK will automatically retry after 15 seconds + // No manual intervention needed + }); + ``` + + +## Automatic Handling + +Ably SDKs automatically handle this error with the following behavior: +- **Initial retry**: After 15 seconds +- **Subsequent retries**: Exponential backoff with jitter +- **State progression**: `disconnected` → `connecting` → `connected` (on success) or `suspended` (after multiple failures) +- **No manual retry needed**: The SDK manages all reconnection attempts + + +## Prevention + +- **Implement connection monitoring**: Add listeners for connection state changes to provide user feedback +- **Handle offline scenarios**: Design your application to gracefully handle periods without connectivity +- **Use environment variables**: Store API keys securely and avoid hardcoding credentials +- **Test across networks**: Verify your application works in various network environments during development + + +## Platform-Specific Considerations + +### Android +- Higher incidence of SSL chain validation failures +- May require specific SSL/TLS configuration for older Android versions +- Consider implementing certificate pinning for enhanced security + + +### Java SDK +- Known issue: WebSocket thread leak on repeated connection failures ([Issue #1144](https://github.com/ably/ably-java/issues/1144)) +- Workaround: Monitor thread count and restart if necessary for long-running applications + + +### Corporate Networks +- WebSocket connections frequently blocked +- May require fallback to HTTP transport +- Consider configuring transport options explicitly + + +## Related Resources + +- [Connection state documentation](https://ably.com/docs/realtime/connection) +- [Authentication guide](https://ably.com/docs/auth) +- [Transport configuration](https://ably.com/docs/realtime/connection#transport-params) +- [Network requirements](https://ably.com/docs/best-practice-guide#connectivity) +- Related errors: [80002 (Suspended)](./80002-connection-suspended.md), [80003 (Disconnected)](./80003-connection-disconnected.md) + +## Need Further Help? + +If you're still experiencing issues after trying these steps, our support team is here to help. + +**Contact Ably Support**: https://ably.com/support + +When contacting support, please provide: +- Your account ID and app ID +- The full error message including error code 80000 +- Steps to reproduce the issue +- Any relevant code snippets (without sensitive credentials) +- The SDK and version you're using + +Our team will help you resolve this issue as quickly as possible. + + + + + + + + + + + + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/80002-connection-suspended.mdx b/src/pages/docs/platform/errors/codes/80002-connection-suspended.mdx new file mode 100644 index 0000000000..3b79ecc3c9 --- /dev/null +++ b/src/pages/docs/platform/errors/codes/80002-connection-suspended.mdx @@ -0,0 +1,185 @@ + + + + + + + + +# Error 80002: Connection suspended + +## What Happened + +Your connection to Ably has been suspended after network connectivity issues prevented a stable connection for more than 2 minutes. + +## Quick Reference + +| Error Code | HTTP Status | Category | Retryable | +|------------|-------------|----------|-----------| +| 80002 | 400/503 | Connection (State) | Yes - automatically handled by SDK | + +## Quick Fix + +- Check your internet connection stability +- Verify WebSocket connections aren't blocked by firewall or proxy +- Connection will automatically retry every 15-30 seconds + +## Error Messages + +You may see one of these messages: +- "Connection to server unavailable" +- "Connection unavailable" +- "Unable to establish connection" (when no connection was ever established) +- "Unable to publish in Suspended state" +- "Connection suspended due to server unavailability code=80002" + +## Common Causes + +1. **Network connectivity issues** (70% of cases) + + - Intermittent WiFi or cellular connectivity + - Moving between cell towers or poor signal areas + - Network interruptions lasting more than 2 minutes + +2. **Network configuration problems** (20% of cases) + + - Corporate firewalls blocking WebSocket connections + - Proxy servers interfering with persistent connections + - Restrictive network policies + +3. **Extended authentication issues** (10% of cases) + + - Token refresh failures during connection attempts + - Credential validation taking too long + +## Resolution Steps + +1. **Verify network connectivity** + + - Test your internet connection stability + - Try switching between WiFi and cellular data + - Move to a location with better signal strength + +2. **Check network environment** + + - Test from a different network (home, office, mobile hotspot) + - Verify WebSocket connections are allowed on port 443 + - Check if corporate firewall or proxy is interfering + +3. **Monitor connection state** + + - The SDK will automatically retry connection every 15-30 seconds + - No manual intervention required - automatic recovery is built-in + - Connection will transition back to `connected` state when network improves + +4. **Handle suspended state in your application** + + - Show appropriate UI feedback to users about connection status + - Queue critical operations locally if needed + - Wait for connection state to become `connected` before resuming operations + +## Automatic Handling + +Ably SDKs automatically handle connection suspension with these behaviors: + +- Retry connection attempts every 15-30 seconds while suspended +- Automatically transition back to `connected` when network recovers +- No exponential backoff needed - SDK manages retry timing +- Messages cannot be published while in suspended state + +## Prevention + + +- Design your app to gracefully handle extended offline periods +- Implement proper connection state monitoring +- Test your app under poor network conditions +- Consider offline functionality for core features + +## Performance Impact + +While connection is suspended: + +- All realtime features (channels, presence, messaging) are unavailable +- Publishing operations will fail with error 80002 +- Presence members are removed from channels +- Recovery may take several minutes depending on network conditions + +## Related Resources + +- [Connection State Management](https://ably.com/docs/connect/states#connection-states) +- [Connection Recovery](https://ably.com/docs/connect/recovery) +- [Network Requirements](https://ably.com/docs/connect#network-requirements) +- Related errors: [80000](./80000-connection-failed.md) (connection failed), [80003](./80003-disconnected.md) (disconnected) + +## Need Further Help? + +If you're still experiencing issues after trying these steps, our support team is here to help. + +**Contact Ably Support**: https://ably.com/support + +When contacting support, please provide: +- Your account ID and app ID +- The full error message including error code 80002 +- Steps to reproduce the issue +- Any relevant code snippets (without sensitive credentials) +- The SDK and version you're using + +Our team will help you resolve this issue as quickly as possible. + + + + + + + + + + + + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/80003-connection-temporarily-unavailable.mdx b/src/pages/docs/platform/errors/codes/80003-connection-temporarily-unavailable.mdx new file mode 100644 index 0000000000..c99581748f --- /dev/null +++ b/src/pages/docs/platform/errors/codes/80003-connection-temporarily-unavailable.mdx @@ -0,0 +1,191 @@ + + + + + + + + +# Error 80003: Connection temporarily unavailable + +## What Happened? + +Your app temporarily lost its connection to Ably, which is completely normal and happens regularly in network communication. + +## Quick Reference + +| Error Code | HTTP Status | Category | Retryable | +|------------|-------------|----------|-----------| +| 80003 | 400/408/500/503 | Connection (Disconnection) | Yes - automatically handled by SDKs | + +## Quick Fix + +- No action required - the SDK automatically reconnects within 15 seconds +- Monitor if disconnections are excessive (multiple times per minute) +- Ensure your app handles brief disconnections gracefully + +## Error Messages + +You may see one of these messages: +- "Connection to server temporarily unavailable" +- "Connection temporarily unavailable" +- "Websocket closed" +- "Transport operation timed out" +- "Unable to connect (network unreachable)" +- "Unable to connect (no available host)" +- "No activity seen from realtime in {interval}; assuming connection has dropped" +- "Transport disconnected unexpectedly" +- "Connection timeout after 3 seconds" (CLI only) +- "No network connection available" (Android) +- "Idle timer expired" + +## Common Causes + +1. **Normal network interruptions** (80% of cases) + + - Brief WiFi hiccups or network maintenance + - Cell tower handoffs on mobile devices + - Network equipment resets or updates + +2. **Mobile device behavior** (15% of cases) + + - Switching between WiFi and cellular data + - Device sleep/wake cycles + - Background app transitions + - Battery optimization pausing network activity + +3. **Authentication updates** (5% of cases) + + - Token renewal causing momentary disconnection + - Credential updates requiring reconnection + +## Resolution Steps + +1. **Let the SDK handle it automatically** + + - Ably SDKs automatically reconnect after detecting a disconnection + - Reconnection typically happens within 15 seconds + - No manual intervention required for normal disconnections + +2. **Design your app for resilience** + + - Queue user actions during brief disconnections + - Implement optimistic UI updates + - Cache important data locally + - Show subtle connection indicators only after a few seconds + +3. **Monitor for excessive disconnections** + + - Check network stability if disconnections happen multiple times per minute + - Test on different networks (WiFi vs cellular) + - Monitor patterns - specific times, locations, or activities + +4. **For persistent issues** + + - If disconnections never resolve automatically + - If all users in a region experience frequent disconnections + - Contact support with connection logs and patterns + +## Automatic Handling + +Ably SDKs handle 80003 errors automatically: + +- Immediate detection of connection loss +- Exponential backoff retry strategy +- Automatic reconnection within 15 seconds +- Message queueing during disconnection (with default settings) +- State recovery after reconnection + +## Prevention + +While disconnections are normal and can't be eliminated entirely, you can minimize their impact: + + +- **Connection Monitoring**: Track patterns to identify unusual behavior +- **Network Optimization**: Use stable connections where possible +- **Graceful Degradation**: Design features to work during brief offline periods +- **User Experience**: Don't alarm users with error messages for brief disconnections + +## Platform-Specific Considerations + +### Android + +- Android 14+ may experience connection instability in background +- Consider closing connection when backgrounded with a delay +- Reconnect when returning to foreground + +### Browser + +- Browser performs connectivity check to `internet-up.ably-realtime.com` +- Shows "Unable to connect (network unreachable)" when offline + +## Related Resources + +- [Connection States Documentation](https://ably.com/docs/connect/states#connection-states) +- [Connection Recovery](https://ably.com/docs/connect/states#connection-recovery) +- [Connection State Events](https://ably.com/docs/connect/states#connection-state-events) +- [Network Connectivity Best Practices](https://ably.com/docs/best-practice#connectivity) + +## Need Further Help? + +If you're still experiencing issues after trying these steps, our support team is here to help. + +**Contact Ably Support**: https://ably.com/support + +When contacting support, please provide: +- Your account ID and app ID +- The full error message including error code 80003 +- Steps to reproduce the issue +- Any relevant code snippets (without sensitive credentials) +- The SDK and version you're using + +Our team will help you resolve this issue as quickly as possible. + + + + + + + + + + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/80008-connection-recovery-expired.mdx b/src/pages/docs/platform/errors/codes/80008-connection-recovery-expired.mdx new file mode 100644 index 0000000000..a97d4879b9 --- /dev/null +++ b/src/pages/docs/platform/errors/codes/80008-connection-recovery-expired.mdx @@ -0,0 +1,203 @@ + + + + + + + + +# Error 80008: Connection recovery expired + +## What happened + +Your app attempted to resume a previous connection to Ably, but the connection had already expired (typically after 2 minutes of disconnection). + +## Quick reference + +| Error Code | HTTP Status | Category | Retryable | +|------------|-------------|----------|-----------| +| 80008 | 400 or 404 | Connection Recovery | Yes - SDK establishes fresh connection automatically | + +## Quick fix + +- Let the SDK establish a fresh connection automatically +- All channels will reattach with `resumed=false` +- Use the history API to retrieve any messages sent during disconnection + +## Error messages + +You may see one of these messages: +- "Unable to recover connection (connection expired)" - Connection state has been cleaned up after 2 minutes +- "Unable to recover connection (unretrievable)" - Recovery data could not be accessed + +## Common causes + + +1. **Extended disconnection** (90% of cases) + - App disconnected for more than 2 minutes + - Mobile app backgrounded for extended period + - Device in sleep mode or airplane mode + - Network outage lasting over 2 minutes + + +2. **Network instability** (8% of cases) + - Prolonged poor network conditions preventing timely reconnection + - Connection attempts failing repeatedly during the 2-minute window + +3. **App lifecycle events** (2% of cases) + - User switching between apps for extended periods + - Browser tab suspended or inactive + +## Resolution steps + + +1. **Accept the fresh connection** + - The SDK automatically establishes a new connection + - No manual intervention required for the connection itself + - All channels automatically reattach without the resume flag + + +2. **Handle potential message gaps** + - If message continuity is critical, use the history API: + ```javascript + // Retrieve messages from the last known point + const history = await channel.history({ + start: lastKnownMessageTimestamp + }); + + // Process missed messages + history.items.forEach(message => { + if (message.timestamp > lastKnownMessageTimestamp) { + processMessage(message); + } + }); + ``` + + + +3. **Restore application state** + - Re-enter presence if your app uses presence features + - Rebuild any connection-dependent state + - Update UI to reflect fresh connection status + + +4. **Monitor connection state for debugging** + ```javascript + ably.connection.on('connected', (stateChange) => { + if (stateChange.reason?.code === 80008) { + console.log('Fresh connection established after recovery failure'); + // Handle recovery failure if needed + } + }); + ``` + + +## Automatic handling + + +Ably SDKs automatically handle this error by: +- Establishing a fresh connection with a new connection ID +- Reattaching all channels (with `resumed=false`) +- Re-entering presence members (except when using page refresh recovery) +- No manual reconnection logic needed + +## Prevention + + +- **Mobile apps**: Handle foreground/background transitions properly +- **Connection monitoring**: Implement connection state monitoring for critical applications +- **State management**: Design your app to handle fresh connections gracefully +- **History persistence**: Enable channel persistence if message continuity is critical + +## Understanding connection recovery + + +Ably maintains connection state for 2 minutes after disconnection: +- **Within 2 minutes**: Connections can resume with full state recovery +- **After 2 minutes**: Connection state is cleaned up to conserve resources +- **Fresh connection**: A new connection is established with new connection ID + +This is normal behavior and not a failure - it ensures efficient resource management while providing a reasonable recovery window. + +## Related resources + +- [Connection state recovery documentation](https://ably.com/docs/connect/states#connection-state-recovery) +- [History API for message retrieval](https://ably.com/docs/storage-history/history) +- [Presence recovery patterns](https://ably.com/docs/presence/presence#connection-recovery) +- Related errors: [80002](https://help.ably.io/error/80002) (suspended state), [80003](https://help.ably.io/error/80003) (disconnected state) + +## Need further help? + +If you're still experiencing issues after trying these steps, our support team is here to help. + +**Contact Ably Support**: https://ably.com/support + +When contacting support, please provide: +- Your account ID and app ID +- The full error message including error code 80008 +- Steps to reproduce the issue +- Any relevant code snippets (without sensitive credentials) +- The SDK and version you're using + +Our team will help you resolve this issue as quickly as possible. + + + + + + + + + + + + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/80009-connection-transport-unavailable.mdx b/src/pages/docs/platform/errors/codes/80009-connection-transport-unavailable.mdx new file mode 100644 index 0000000000..b204e558d6 --- /dev/null +++ b/src/pages/docs/platform/errors/codes/80009-connection-transport-unavailable.mdx @@ -0,0 +1,187 @@ + + + + + + + + +# Error 80009: Connection transport unavailable + +## What Happened + +The connection to Ably exists but the underlying network transport that carries data is missing or unavailable. + +## Quick Reference + +| Error Code | HTTP Status | Category | Retryable | +|------------|-------------|----------|-----------| +| 80009 | 500 | Connection Error | Yes - requires new connection | + +## Quick Fix + +- Close the current connection completely +- Wait briefly for cleanup (1-2 seconds) +- Establish a fresh connection with new client instance + +## Error Messages + +You may see one of these messages: +- "Connection not established no transport handle: {connectionId}" +- "auth_callback failed: {error message}" (Ruby SDK) +- "auth_url failed: {error message}" (Ruby SDK) + +## Common Causes + +1. **Transport initialization failure** (60% of cases) + - Network transport never properly initialized + - Transport cleaned up while still needed + - Platform-specific network restrictions + + +2. **Authentication operation failures** (30% of cases) + - Auth callback throwing exceptions + - Auth URL request failing or timing out + - Token request operations interrupted + + +3. **Comet transport issues** (10% of cases - historical) + - Comet fallback transport failing on certain browsers + - Transport POST requests returning 404 + - Windows Chrome environments affected + + +## Resolution Steps + +1. **Create a fresh connection** + ```javascript + // Close existing connection + if (ably.connection.state !== 'closed') { + ably.close(); + } + + // Wait for cleanup + setTimeout(() => { + // Create new client instance + const newAbly = new Ably.Realtime({ key: apiKey }); + + // Monitor connection state + newAbly.connection.on('connected', () => { + console.log('Successfully reconnected'); + }); + }, 1000); + ``` + + +2. **For authentication-related failures (Ruby SDK)** + - Verify auth callback completes within timeout period + - Check auth URL endpoint is responsive + - Ensure network connectivity during token requests + + +3. **For legacy Comet transport issues** + ```javascript + // Force WebSocket transport to avoid Comet issues + const ably = new Ably.Realtime({ + key: apiKey, + transports: ['web_socket'] + }); + ``` + + +4. **Monitor system resources** + - Check device memory usage + - Restart app if memory usage is high + - Close other network-intensive applications + + +## Automatic Handling + +Ably SDKs do not automatically recover from this error. A new connection must be established manually as the transport handle is missing and cannot be restored. + + +## Prevention + +- Always close connections properly before creating new ones +- Don't attempt to reuse connection objects that have failed +- Implement proper connection lifecycle management +- For web applications, consider forcing WebSocket transport if Comet issues occur + + +## Related Resources + +- [Connection state management](https://ably.com/docs/realtime/connection) +- [Authentication documentation](https://ably.com/docs/auth) +- [Transport selection](https://ably.com/docs/realtime/connection#transport) +- Related errors: [80000](https://help.ably.io/error/80000), [80002](https://help.ably.io/error/80002), [80003](https://help.ably.io/error/80003) + +## Need Further Help? + +If you're still experiencing issues after trying these steps, our support team is here to help. + +**Contact Ably Support**: https://ably.com/support + +When contacting support, please provide: +- Your account ID and app ID +- The full error message including error code 80009 +- Steps to reproduce the issue +- Any relevant code snippets (without sensitive credentials) +- The SDK and version you're using + +Our team will help you resolve this issue as quickly as possible. + + + + + + + + + + + + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/80010-invalid-transport-handle.mdx b/src/pages/docs/platform/errors/codes/80010-invalid-transport-handle.mdx new file mode 100644 index 0000000000..b610f277a0 --- /dev/null +++ b/src/pages/docs/platform/errors/codes/80010-invalid-transport-handle.mdx @@ -0,0 +1,190 @@ + + + + + + + + +# Error 80010: Invalid transport handle + +## What Happened + +The connection operation cannot proceed because the underlying transport handle is in an invalid or unexpected state. + +## Quick Reference + +| Error Code | HTTP Status | Category | Retryable | +|------------|-------------|----------|-----------| +| 80010 | 400 | Connection (Client) | No - requires state validation | + +## Quick Fix + +- Check your connection state before attempting operations +- Wait for the connection to reach `connected` state +- Implement proper connection state event listeners + +## Error Messages + +You may see this message in iOS/macOS applications: +- "Invalid operation (connection state is [state number] - [state name])" + +The message includes the actual connection state for debugging purposes. + +## Common Causes + +1. **Attempting operations during state transitions** (most common) + - Trying to publish or subscribe while connection is changing states + - Race conditions between multiple connection operations + + +2. **Invalid connection state** + - Connection is in an unexpected or undefined state + - Transport handle has been superseded or invalidated + + +3. **SDK lifecycle issues** + - Improper connection initialization sequence + - Missing state validation before operations + + +## Resolution Steps + +1. **Validate connection state before operations** + ```swift + // iOS/macOS - Check connection state first + if realtime.connection.state == .connected { + // Safe to perform operations + channel.publish("event", data: message) + } else { + // Wait for connection + realtime.connection.on(.connected) { + channel.publish("event", data: message) + } + } + ``` + + +2. **Implement proper state listeners** + ```swift + // Monitor connection state changes + realtime.connection.on { stateChange in + switch stateChange.current { + case .connected: + // Connection ready for operations + performPendingOperations() + case .connecting, .disconnected: + // Queue operations or show waiting state + queueOperations() + case .suspended, .failed, .closed: + // Handle error states + handleConnectionError(stateChange.reason) + default: + break + } + } + ``` + + +3. **Handle timing and race conditions** + - Avoid rapid successive connection operations + - Use connection promises or callbacks instead of assuming immediate state + - Implement proper error handling for state conflicts + + +4. **Review your connection management** + - Ensure proper SDK initialization + - Verify connection lifecycle handling + - Check for concurrent operations that might conflict + + +## Automatic Handling + +The Ably SDK does not automatically retry this error as it indicates a client-side state validation issue that requires your application to check the connection state and retry when appropriate. + +## Prevention + +- **Always validate connection state** before performing operations +- **Use event-driven patterns** - listen for connection state changes rather than assuming state +- **Implement proper error handling** for all connection operations +- **Design for connection lifecycle** - structure your app flow around connection states + + +## Platform Information + +This error code is specific to the **iOS/macOS (Cocoa) SDK**. Other SDKs may handle similar scenarios with different error codes or mechanisms. + + +## Related Resources + +- [Connection State Management](https://ably.com/docs/realtime/connection#connection-state-explained) +- [iOS SDK Documentation](https://ably.com/docs/realtime/usage#connection) +- [Connection State Recovery](https://ably.com/docs/realtime/connection#connection-state-recovery) +- Related errors: [80000](https://help.ably.io/error/80000) (connection failed), [80003](https://help.ably.io/error/80003) (disconnected), [80009](https://help.ably.io/error/80009) (connection not established) + +## Need Further Help? + +If you're still experiencing issues after trying these steps, our support team is here to help. + +**Contact Ably Support**: https://ably.com/support + +When contacting support, please provide: +- Your account ID and app ID +- The full error message including error code 80010 +- Steps to reproduce the issue +- Any relevant code snippets (without sensitive credentials) +- The SDK and version you're using + +Our team will help you resolve this issue as quickly as possible. + + + + + + + + + + + + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/80013-protocol-error.mdx b/src/pages/docs/platform/errors/codes/80013-protocol-error.mdx new file mode 100644 index 0000000000..5b10abd29e --- /dev/null +++ b/src/pages/docs/platform/errors/codes/80013-protocol-error.mdx @@ -0,0 +1,168 @@ + + + + + + + + +# Error 80013: Protocol Error + +## What Happened + +The communication between your application and Ably's servers encountered a protocol violation, meaning one side sent a message the other couldn't understand or process correctly. + +## Quick Reference + +| Error Code | HTTP Status | Category | Retryable | +|------------|-------------|----------|-----------| +| 80013 | 400 | Protocol Error | No - requires fixing the underlying issue | + +## Quick Fix + +- Update to the latest version of your Ably SDK +- Verify your message formats match Ably's protocol specification +- Check that all required fields are present in your messages + +## Error Messages + +You may see one of these messages: +- "Protocol Message Action {action} is unsupported by this MessageDispatcher" +- "Protocol error, unknown presence action {action}" +- "Protocol error, presence message is missing connectionId" +- "Invalid Protocol Message received: {event_data}" +- "protocol error" (with encoding details) +- "msgpack encode error: unsupported payload type status=0, internal=80013" + +## Common Causes + +1. **SDK version incompatibility** (40% of cases) + - Using outdated SDK that doesn't support current protocol features + - SDK version mismatch with server protocol version + + +2. **Missing required fields** (30% of cases) + - Presence messages lacking connectionId + - Protocol messages missing mandatory fields + + +3. **Invalid message actions** (20% of cases) + - Unknown protocol message action types + - Unsupported presence actions + + +4. **Encoding failures** (10% of cases) + - MessagePack encoding errors with struct/object data + - Delta decode failures with VCDiff encoding + + +## Resolution Steps + +1. **Update your SDK to the latest version** + - Check your current SDK version against the [latest releases](https://ably.com/download) + - Review the [changelog](https://github.com/ably/ably-js/releases) for protocol updates + - Update your dependencies and test in a staging environment + + +2. **Verify message format compliance** + - Ensure all required fields are present (especially connectionId for presence messages) + - Follow the [protocol documentation](https://ably.com/docs/realtime/protocol) strictly + - Validate message structures before sending + + +3. **Check for encoding issues** + - If using MessagePack with Go SDK, ensure data is string or byte array, not struct + - For delta encoding issues, consider disabling delta compression temporarily + - Review your data serialization approach + + +4. **Enable debug logging for detailed information** + - Turn on debug logging in your SDK to capture protocol message details + - Look for specific action types or field names mentioned in error messages + - Share logs with Ably support if the issue persists + + +## Automatic Handling + +This is a protocol error that will not be automatically retried. The connection will typically move to a failed state, requiring manual intervention to fix the underlying issue before reconnection can succeed. + + +## Prevention + +- Keep your SDK updated to the latest stable version +- Subscribe to Ably's release notifications for protocol updates +- Implement comprehensive error handling for protocol errors +- Test your application with various message types and formats +- Follow Ably's API documentation strictly for message formatting + + +## Related Resources + +- [Protocol Documentation](https://ably.com/docs/realtime/protocol) +- [SDK Downloads](https://ably.com/download) +- [Connection State Management](https://ably.com/docs/realtime/connection) +- [Message Encoding](https://ably.com/docs/realtime/types) + +## Need Further Help? + +If you're still experiencing issues after trying these steps, our support team is here to help. + +**Contact Ably Support**: https://ably.com/support + +When contacting support, please provide: +- Your account ID and app ID +- The full error message including error code 80013 +- Steps to reproduce the issue +- Any relevant code snippets (without sensitive credentials) +- The SDK and version you're using + +Our team will help you resolve this issue as quickly as possible. + + + + + + + + + + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/80014-connection-timeout.mdx b/src/pages/docs/platform/errors/codes/80014-connection-timeout.mdx new file mode 100644 index 0000000000..a59e23946f --- /dev/null +++ b/src/pages/docs/platform/errors/codes/80014-connection-timeout.mdx @@ -0,0 +1,175 @@ + + + + + + + + +# Error 80014: Connection timed out + +## What Happened + +Your application couldn't establish a connection to Ably within the timeout period, similar to calling someone and waiting too long without an answer. + +## Quick Reference + +| Error Code | HTTP Status | Category | Retryable | +|------------|-------------|----------|-----------| +| 80014 | 504/408 | Connection | Yes - SDK retries automatically | + +## Quick Fix + +- Check your internet connection is stable +- Verify firewall allows access to Ably endpoints +- Consider increasing timeout if on slow network + +## Error Messages + +You may see one of these messages: +- "Unable to establish connection" +- "Connecting timeout" +- "Connection to Ably timed out after 10s" +- Request timeout errors from REST operations + +## Common Causes + +1. **Network connectivity issues** (60% of cases) + - Slow or unstable internet connection + - Network congestion during peak times + - Mobile network switching between towers + + +2. **Firewall or proxy restrictions** (25% of cases) + - Corporate firewalls blocking WebSocket connections + - Proxy servers adding significant overhead + - Security scanning delays in enterprise networks + + +3. **Geographic distance** (10% of cases) + - Connecting from far away from nearest Ably data center + - International connections with high latency + + +4. **Timeout configuration too strict** (5% of cases) + - Default 10-second timeout insufficient for network conditions + - Mobile or satellite connections needing longer timeouts + + +## Resolution Steps + +1. **Verify network connectivity** + - Test your internet connection stability + - Try connecting from a different network + - Check connection without VPN or proxy + + +2. **Check firewall configuration** + - Ensure access to `*.ably.io` domains on ports 80 and 443 + - Verify WebSocket connections are allowed + - Test from outside corporate network to isolate firewall issues + + +3. **Adjust timeout settings for your network conditions** + - Increase `realtimeRequestTimeout` for slower networks + - Configure appropriate timeouts for mobile applications + - See [Connection Options Documentation](https://ably.com/docs/realtime/connection#client-options) for configuration details + + +4. **Monitor connection patterns** + - Track when timeouts occur most frequently + - Identify correlation with network usage or time of day + - Adjust timeout strategy based on observed patterns + + +## Automatic Handling + +Ably SDKs automatically retry connection attempts after timeouts with exponential backoff. You don't need to implement your own retry logic. The SDK will: +- Retry the connection automatically +- Use progressive backoff to avoid overwhelming the network +- Eventually establish connection when network conditions improve + + +## Prevention + +- **Configure appropriate timeouts**: Set realistic timeout values based on your users' network environment +- **Implement connection quality monitoring**: Detect network conditions and adapt behavior accordingly +- **Design for offline scenarios**: Build your application to handle temporary disconnections gracefully +- **Use regional endpoints**: Connect to the nearest Ably data center for optimal performance + + +## Related Resources + +- [Connection Configuration Guide](https://ably.com/docs/realtime/connection#client-options) +- [Connection State Management](https://ably.com/docs/realtime/connection#connection-state-recovery) +- [Network Requirements](https://ably.com/docs/best-practice-guide#connectivity) +- [Status Page](https://status.ably.com) + +## Need Further Help? + +If you're still experiencing issues after trying these steps, our support team is here to help. + +**Contact Ably Support**: https://ably.com/support + +When contacting support, please provide: +- Your account ID and app ID +- The full error message including error code 80014 +- Steps to reproduce the issue +- Any relevant code snippets (without sensitive credentials) +- The SDK and version you're using + +Our team will help you resolve this issue as quickly as possible. + + + + + + + + + + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/80016-operation-on-superseded-connection.mdx b/src/pages/docs/platform/errors/codes/80016-operation-on-superseded-connection.mdx new file mode 100644 index 0000000000..569d6860fe --- /dev/null +++ b/src/pages/docs/platform/errors/codes/80016-operation-on-superseded-connection.mdx @@ -0,0 +1,195 @@ + + + + + + + + +# Error 80016: Operation on Superseded Connection + +## What Happened + +You attempted an operation on a connection that has been replaced by a newer one, typically during a transport upgrade from HTTP to WebSocket. + +## Quick Reference + +| Error Code | HTTP Status | Category | Retryable | +|------------|-------------|----------|-----------| +| 80016 | 410 (Gone) | Connection/Transport | Yes - SDK handles automatically | + +## Quick Fix + +- No immediate action needed - Ably SDKs handle this automatically +- Ensure you're using the latest connection reference in your code +- Monitor if the connection successfully recovers + +## Error Messages + +You may see one of these messages: +- "Unable to find connection: [connectionKey]" +- "Invalid transport id: [transportId]" +- "Operation on superseded connection" +- "Error occurred during connection" + + + +## Common Causes + +1. **Transport Upgrade** (90% of cases) + - Normal behavior when upgrading from Comet (HTTP) to WebSocket + - Old HTTP requests arrive after WebSocket connection is established + - Server rejects requests for the superseded transport + + +2. **Network Transitions** (5% of cases) + - Switching between WiFi and mobile data + - App moving between foreground and background + - Network connectivity changes + + +3. **Multiple Connections** (5% of cases) + - Multiple browser tabs or app instances + - Race conditions during connection attempts + - Competing connections from the same client + + +## Resolution Steps + +1. **Let the SDK handle it** + - Ably SDKs automatically manage connection supersession + - The SDK will check pending state and recover transparently + - No manual intervention required in most cases + + +2. **Monitor connection state** + ```javascript + ably.connection.on('connected', () => { + console.log('Connection recovered successfully'); + }); + + ably.connection.on('failed', (stateChange) => { + console.error('Connection failed:', stateChange.reason); + // Only take action if connection doesn't recover + }); + ``` + + +3. **Verify connection recovery** + - Check if the connection state becomes `connected` + - Ensure operations resume normally + - Only investigate if the client never becomes connected + + +4. **If errors persist** + - Check for frequent occurrences without network changes + - Verify your app properly handles connection lifecycle + - Ensure you're not storing and reusing old connection references + + +## Automatic Handling + +Ably SDKs implement sophisticated handling for this error: +- The SDK calls `checkPendingState()` when error 80016 is received +- Connection recovery is attempted automatically +- Transport upgrade race conditions are managed internally +- The error is not propagated to your application if recovery succeeds + + + +## Prevention + +- **Use connection state events**: Always work with the current connection state rather than stored references +- **Implement proper lifecycle handling**: Handle app backgrounding/foregrounding correctly +- **Avoid storing connection references**: Use the SDK's current connection instance +- **Test network transitions**: Verify your app handles network changes gracefully + + + +## Performance Impact + +This error has minimal performance impact: +- Occurs briefly during normal transport upgrades +- Recovery is typically within milliseconds +- No data loss as operations are retried on the new connection +- Transparent to end users in most cases + + + +## Related Resources + +- [Connection State Management](https://ably.com/docs/realtime/connection) +- [Transport Mechanisms](https://ably.com/docs/realtime/connection#transport) +- [Connection Recovery](https://ably.com/docs/realtime/connection#connection-recovery) +- Related errors: [80000](./80000-connection-failed.mdx), [80003](./80003-connection-suspended.mdx) + +## Need Further Help? + +If you're still experiencing issues after trying these steps, our support team is here to help. + +**Contact Ably Support**: https://ably.com/support + +When contacting support, please provide: +- Your account ID and app ID +- The full error message including error code 80016 +- Steps to reproduce the issue +- Any relevant code snippets (without sensitive credentials) +- The SDK and version you're using + +Our team will help you resolve this issue as quickly as possible. + + + + + + + + + + + + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/80017-connection-closed.mdx b/src/pages/docs/platform/errors/codes/80017-connection-closed.mdx new file mode 100644 index 0000000000..a5a2adaa7b --- /dev/null +++ b/src/pages/docs/platform/errors/codes/80017-connection-closed.mdx @@ -0,0 +1,224 @@ + + + + + + + + +# Error 80017: Connection closed + +## What Happened + +Your connection to Ably has been closed and is no longer available for sending or receiving messages. + +## Quick Reference + +| Error Code | HTTP Status | Category | Retryable | +|------------|-------------|----------|-----------| +| 80017 | 400 | Connection State | Yes - after establishing new connection | + +## Quick Fix + +- Check if the closure was intentional (your code called `close()`) +- Verify your network connectivity is stable +- Create a new connection if you need to continue using Ably + +## Error Messages + +You may see one of these messages: +- "Connection closing" +- "Connection closed" +- "Connection unavailable" +- "connection broken before receiving publishing acknowledgment" +- "Connection closed - OS network offline" + +## Common Causes + +1. **Intentional disconnect** (40% of cases) + + - Your application explicitly called `connection.close()` + - App cleanup during shutdown + - User-triggered disconnection + +2. **Network connectivity loss** (30% of cases) + + - WiFi disconnected or unstable + - Mobile signal lost + - Network interface changed (WiFi to mobile data) + - OS-level network offline + +3. **App lifecycle events** (20% of cases) + + - Mobile app backgrounded + - Browser tab unloaded + - Desktop app sleep/wake cycles + +4. **Operations on closed connection** (10% of cases) + + - Calling channel methods after connection closed + - Attempting presence updates on closed connection + - Publishing messages after closure + +## Important Note About This Error + +Error 80017 often appears in logs as a normal state transition reason, not always as an actual error. When you see it in verbose logs during connection state changes, this is expected behavior: + +``` +Connection state: closing reason: Connection closing (80017) +Connection state: closed reason: Connection closed (80017) +``` + + +This is only an error when you attempt to perform operations on an already closed connection. + +## Resolution Steps + +1. **Check connection state before operations** + + ```javascript + if (ably.connection.state === 'connected') { + // Safe to perform operations + channel.publish('message', data); + } + ``` + +2. **Monitor connection state changes** + + ```javascript + ably.connection.on('closed', (stateChange) => { + console.log('Connection closed:', stateChange.reason); + // Handle closure based on reason + }); + ``` + +3. **Establish a new connection if needed** + + ```javascript + // Create new Ably client instance + const ably = new Ably.Realtime({ key: apiKey }); + + // Or reconnect existing client + ably.connect(); + ``` + +4. **Implement appropriate reconnection strategy** + + - For network issues: Automatic reconnection is appropriate + - For intentional closure: Only reconnect if needed + - For app lifecycle: Reconnect when app becomes active + +## Automatic Handling + +Ably SDKs do not automatically reconnect after an intentional connection closure (error 80017). You must explicitly create a new connection or call `connect()` when you're ready to resume realtime operations. + + +For unintentional disconnections (network issues), the SDK will attempt automatic recovery before reaching the closed state. + +## Prevention + +- **Check connection state** before performing operations + +- **Handle app lifecycle events** properly on mobile and web platforms + +- **Implement connection monitoring** to detect and respond to closures + +- **Clean up connections** properly when no longer needed + +## Platform-Specific Considerations + +### Mobile Apps +Handle app backgrounding and network changes: +```javascript +// React Native example +AppState.addEventListener('change', (state) => { + if (state === 'active') { + ably.connect(); + } +}); +``` + + +### Web Applications +The JavaScript SDK closes connections automatically on page unload by default (`closeOnUnload: true`). + + +## Related Resources + +- [Connection state management documentation](https://ably.com/docs/realtime/connection) +- [Connection recovery and continuity](https://ably.com/docs/realtime/connection#connection-state-recovery) +- [Handling connection failures](https://ably.com/docs/best-practice-guide#handling-failures) +- Related errors: [80000](./80000-connection-failed.md), [80002](./80002-connection-suspended.md), [80003](./80003-connection-disconnected.md) + +## Need Further Help? + +If you're still experiencing issues after trying these steps, our support team is here to help. + +**Contact Ably Support**: https://ably.com/support + +When contacting support, please provide: +- Your account ID and app ID +- The full error message including error code 80017 +- Steps to reproduce the issue +- Any relevant code snippets (without sensitive credentials) +- The SDK and version you're using + +Our team will help you resolve this issue as quickly as possible. + + + + + + + + + + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/80018-invalid-connection-id.mdx b/src/pages/docs/platform/errors/codes/80018-invalid-connection-id.mdx new file mode 100644 index 0000000000..05536391e1 --- /dev/null +++ b/src/pages/docs/platform/errors/codes/80018-invalid-connection-id.mdx @@ -0,0 +1,176 @@ + + + + + + + + +# Error 80018: Invalid connection ID + +## What Happened + +The connection ID provided to Ably doesn't match the expected format or is invalid. + +## Quick Reference + +| Error Code | HTTP Status | Category | Retryable | +|------------|-------------|----------|-----------| +| 80018 | 400 | Connection Error (Authentication) | No - requires valid connection ID | + +## Quick Fix + +- Let the Ably SDK manage connection IDs automatically +- Don't manually create or modify connection IDs +- If using ably-js versions 1.2.30-1.2.33, upgrade to the latest version + +## Error Messages + +You may see one of these messages: +- "Invalid connection key WHAT NODE" +- "Invalid connection serial" +- "invalid connection id (invalid format)" +- "invalid connectionKey: [key]. See https://help.ably.io/error/80018" + +## Common Causes + +1. **SDK bug in ably-js 1.2.30-1.2.33** (most common for SDK users) + - Known bug causing connection resume failures + - Fixed in versions after 1.2.33 + + +2. **Manually created connection IDs** (common mistake) + - Attempting to construct connection IDs instead of using SDK-provided ones + - Connection IDs must be generated by Ably, not clients + + +3. **Corrupted connection data** (less common) + - Connection ID corrupted during storage or transmission + - Network issues causing data corruption + - Truncated or incomplete connection IDs + + +4. **Invalid connection serial number** + - Connection serial is not a valid number (NaN) + - Occurs during connection state synchronization + + +## Resolution Steps + +1. **Check your SDK version** + - If using ably-js versions 1.2.30 through 1.2.33, upgrade immediately + - This resolves the known connection resume bug + + +2. **Use SDK-managed connection IDs** + ```javascript + // ✅ Correct: Let the SDK handle connection IDs + const ably = new Ably.Realtime({ key: apiKey }); + ably.connection.on('connected', () => { + // Connection ID is automatically managed + console.log('Connected with ID:', ably.connection.id); + }); + + // ❌ Wrong: Never manually create connection IDs + // const fakeConnectionId = 'my-connection-123'; + ``` + + +3. **Establish a new connection** + - If the error persists, establish a fresh connection + - Don't try to recover using stored connection IDs + - Let the SDK handle the entire connection lifecycle + + +4. **Review your implementation** + - Remove any code that manually handles connection IDs + - Don't store connection IDs in localStorage or databases + - Don't modify SDK-provided connection IDs + + +## Automatic Handling + +Ably SDKs automatically manage connection IDs and connection lifecycle. This error indicates that the automatic handling has been bypassed or a bug exists in older SDK versions. The SDK will not automatically retry this error as it requires a valid connection ID format. + + +## Prevention + +- **Always use the latest SDK version** to avoid known bugs +- **Never manually create or modify connection IDs** - they have specific format requirements +- **Let the SDK manage the entire connection lifecycle** including ID generation +- **Don't persist connection IDs** across application sessions +- **Implement proper error handling** for connection operations + + +## Related Resources + +- [Connection State Management](https://ably.com/docs/realtime/connection) +- [FAQ: Error Code 80018](https://faqs.ably.com/error-code-80018-invalid-connection-id-invalid-format) +- Related errors: [80023](./80023-unable-to-resume-connection.md) (connection resume failure) + +## Need Further Help? + +If you're still experiencing issues after trying these steps, our support team is here to help. + +**Contact Ably Support**: https://ably.com/support + +When contacting support, please provide: +- Your account ID and app ID +- The full error message including error code 80018 +- Steps to reproduce the issue +- Any relevant code snippets (without sensitive credentials) +- The SDK and version you're using + +Our team will help you resolve this issue as quickly as possible. + + + + + + + + + + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/80019-auth-provider-request-failed.mdx b/src/pages/docs/platform/errors/codes/80019-auth-provider-request-failed.mdx new file mode 100644 index 0000000000..4947015c31 --- /dev/null +++ b/src/pages/docs/platform/errors/codes/80019-auth-provider-request-failed.mdx @@ -0,0 +1,200 @@ + + + + + + + + +# Error 80019: Authentication provider request failed + +## What Happened + +Your app's authentication setup failed when trying to obtain credentials from your configured auth provider (authCallback or authUrl). + +## Quick Reference + +| Error Code | HTTP Status | Category | Retryable | +|------------|-------------|----------|-----------| +| 80019 | 401/403/500 | Connection Error (Authentication) | Depends - No for 403, Yes for others | + +## Quick Fix + +- Check your authCallback or authUrl is working correctly +- Verify the auth response format matches Ably's requirements +- Test your auth endpoint independently to ensure it returns valid credentials + +## Error Messages + +You may see one of these messages: +- "Client configured authentication provider request failed" +- "Client configured authentication provider returned 403; failing the connection" +- "authCallback failed with an exception" +- "authUrl failed with an exception" +- "Empty response received from authUrl" +- "timed out" (iOS/macOS) + +## Common Causes + +1. **Auth callback throwing exceptions** (40% of cases) + - Unhandled errors in your authCallback function + - Wrong return type from callback (e.g., returning object instead of dict in Python) + - Missing error handling in callback code + + +2. **Auth URL returning errors** (30% of cases) + - Auth server returning 4xx or 5xx status codes + - Network connectivity issues reaching auth server + - Auth server down or misconfigured + + +3. **Empty or malformed auth response** (20% of cases) + - Auth provider returning null or empty response + - Invalid JSON format in response + - Missing required fields (token, expires, capability) + + +4. **Serialization issues** (10% of cases) + - Problems serializing capability field in .NET + - JSON parsing errors with auth response + + +## Resolution Steps + +1. **Check the error's cause field** + - The 80019 error includes a `cause` field with the underlying error + - This reveals the specific problem with your auth provider + + +2. **For authCallback errors** + - Add proper error handling to your callback: + ```javascript + authCallback: function(tokenParams, callback) { + try { + // Your auth logic here + const tokenDetails = generateToken(tokenParams); + callback(null, tokenDetails); + } catch (error) { + console.error('Auth callback failed:', error); + callback(error); + } + } + ``` + + - Ensure you're returning the correct type (dict/object as expected by SDK) + - For debugging, use authCallback instead of authUrl for better visibility + + +3. **For authUrl errors** + - Test your auth URL directly with curl or a browser + - Verify it returns valid JSON with required fields: + ```json + { + "token": "your-jwt-token", + "expires": 1234567890000, + "capability": {"*": ["*"]} + } + ``` + + - Check server logs for errors + - Ensure the endpoint is accessible from your app + +4. **For 403 responses** + - This indicates a permanent authentication failure + - The connection will move to "failed" state and won't retry + - Fix the authentication issue on your server before reconnecting + + +5. **For .NET serialization issues** + - Use `CreateTokenRequestAsync` instead of `CreateTokenRequestObjectAsync` + - Ensure capability field is properly formatted + + +## Automatic Handling + +- **403 errors**: Connection moves to "failed" state (permanent failure, no automatic retry) +- **401/other errors**: Connection moves to "disconnected" state (SDK will retry with backoff) +- **Timeout errors**: Behavior varies by SDK (failed or disconnected state) + + +## Prevention + +- Implement robust error handling in auth callbacks +- Validate auth responses before returning them +- Set reasonable timeouts for auth requests +- Monitor your auth server health and availability +- Test authentication under various network conditions + + +## Related Resources + +- [Authentication documentation](https://ably.com/docs/auth) +- [Token authentication guide](https://ably.com/docs/auth/token) +- [authCallback documentation](https://ably.com/docs/auth/token#auth-callback) +- [authUrl documentation](https://ably.com/docs/auth/token#auth-url) +- Related errors: [40170](./40170-error-from-client-token-callback.md) (often appears alongside 80019) + +## Need Further Help? + +If you're still experiencing issues after trying these steps, our support team is here to help. + +**Contact Ably Support**: https://ably.com/support + +When contacting support, please provide: +- Your account ID and app ID +- The full error message including error code 80019 +- Steps to reproduce the issue +- Any relevant code snippets (without sensitive credentials) +- The SDK and version you're using + +Our team will help you resolve this issue as quickly as possible. + + + + + + + + + + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/80023-unable-to-resume-connection-from-another-site.mdx b/src/pages/docs/platform/errors/codes/80023-unable-to-resume-connection-from-another-site.mdx new file mode 100644 index 0000000000..8c45b2fd19 --- /dev/null +++ b/src/pages/docs/platform/errors/codes/80023-unable-to-resume-connection-from-another-site.mdx @@ -0,0 +1,207 @@ + + + + + + + + +# Error 80023: Unable to resume connection from another site + +## What Happened + +Your app tried to resume a connection at a different Ably data center than where it was originally established, which is not supported for consistency and performance reasons. + +## Quick Reference + +| Error Code | HTTP Status | Category | Retryable | +|------------|-------------|----------|-----------| +| 80023 | 400 | Connection (Resume) | No - requires new connection | + +## Quick Fix + +- Let the SDK establish a fresh connection automatically +- Don't try to force resumption - the SDK handles this +- Re-attach to channels after the new connection is established + +## Error Messages + +You may see this message: +- "Unable to resume connection from another site" + +## Common Causes + +1. **Geographic movement** (40% of cases) + + - You or your users physically moved to a different region + - Mobile users traveling between countries + - Device switching between WiFi and cellular networks + +2. **Network routing changes** (35% of cases) + + - ISP routing changes directing traffic to different data center + - VPN connection changes or switching locations + - Corporate network policy updates + +3. **Fallback host connection** (25% of cases) + + - Primary endpoint fails and client connects to fallback host + - Load balancer redirects to different site + - DNS changes pointing to different Ably region + +## Resolution Steps + +1. **Allow automatic recovery** + + - The SDK will automatically establish a new connection + - Don't implement manual retry logic - it's handled for you + - Wait for the connection state to become `connected` + +2. **Re-establish channel state** + + - Channels will need to be re-attached + - Presence state will be re-entered automatically + - Channel continuity may be lost - retrieve missed messages using history if needed + +3. **Handle in your application** + + ```javascript + ably.connection.on('connected', (stateChange) => { + if (stateChange.reason?.code === 80023) { + // Connection established at new site + // Re-initialize any local state if needed + console.log('Connection resumed at new location'); + } + }); + ``` + + +4. **Retrieve missed messages if needed** + + - Use channel history to get any messages sent during disconnection + - See [History documentation](https://ably.com/docs/storage-history/history) + +## Automatic Handling + +Ably SDKs automatically handle this error by: + +- Establishing a fresh connection at the optimal site +- Re-attaching to channels automatically +- Maintaining message ordering within the new connection +- Preserving your authentication credentials + +## Prevention + +To minimize the impact of cross-site connection changes: + +1. **Design for stateless connections** + + - Don't rely on persistent server-side connection state + - Store critical state client-side where appropriate + - Design your app to handle connection interruptions gracefully + +2. **Implement robust reconnection handling** + + - Monitor connection state changes + - Handle channel re-attachment transparently + - Provide appropriate UI feedback during reconnection + +3. **Test geographic scenarios** + + - Test with VPN location changes + - Simulate network provider switches + - Verify behavior when moving between regions + +## Why This Error Exists + +This error protects important system guarantees: + +- **Message ordering**: Ensures messages remain in correct sequence +- **Presence consistency**: Maintains accurate member state +- **Performance optimization**: Routes you to the nearest data center +- **Data locality**: Respects regional data requirements + +## Mobile Considerations + +Mobile applications are particularly affected because: + +- Users physically move between regions +- Network switching (WiFi to cellular) can change routing +- Apps backgrounded in one location may resume in another +- Mobile networks can change routing unexpectedly + +## Related Resources + +- [Ably Global Infrastructure](https://ably.com/docs/general/global) +- [Connection State Management](https://ably.com/docs/realtime/connection) +- [Channel History](https://ably.com/docs/storage-history/history) +- [FAQ: Error Code 80023](https://faqs.ably.com/error-code-80023-unable-to-resume-connection-from-a-different-site) +- Related errors: [80002](https://ably.com/docs/errors/80002), [80018](https://ably.com/docs/errors/80018) + +## Need Further Help? + +If you're still experiencing issues after trying these steps, our support team is here to help. + +**Contact Ably Support**: https://ably.com/support + +When contacting support, please provide: +- Your account ID and app ID +- The full error message including error code 80023 +- Steps to reproduce the issue +- Any relevant code snippets (without sensitive credentials) +- The SDK and version you're using + +Our team will help you resolve this issue as quickly as possible. + + + + + + + + + + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/90000-channel-operation-failed.mdx b/src/pages/docs/platform/errors/codes/90000-channel-operation-failed.mdx new file mode 100644 index 0000000000..0df935b53f --- /dev/null +++ b/src/pages/docs/platform/errors/codes/90000-channel-operation-failed.mdx @@ -0,0 +1,204 @@ + + + + + + + + +# Error 90000: Channel operation failed + +## What Happened? + +A channel operation couldn't be completed due to conflicting requests, invalid state, or timing issues with attach/detach operations. + +## Quick Reference + +| Error Code | HTTP Status | Category | Retryable | +|------------|-------------|----------|-----------| +| 90000 | 400/409/500 | Channel Operation | Yes - after resolving conflict | + +## Quick Fix + +- Ensure sequential channel operations (await attach before detach) +- Check channel state before operations +- Implement debouncing for rapid DOM manipulation scenarios + +## Error Messages + +You may see one of these messages: + +- "Attach request superseded by a subsequent detach request" +- "Detach request superseded by a subsequent attach request" +- "Unable to attach; reason unknown; state = {state}" +- "Unable to detach; reason unknown; state = {state}" +- "Can't attach when not in an active state" +- "Channel state is failed" +- "channel is being DETACHED" + +## Common Causes + + +1. **Race conditions between attach/detach** (60% of cases) + - Calling detach() while attach() is pending + - Calling attach() while detach() is pending + - Rapid DOM manipulation triggering multiple operations + +2. **Invalid channel or connection state** (30% of cases) + - Attempting operations on failed channels + - Operations when connection isn't active + - Channel already in detaching state + +3. **Unknown attachment failures** (10% of cases) + - Connection issues during attachment + - Internal server errors + - Timeout during channel operations + +## Resolution Steps + +1. **For attach/detach conflicts** + + - Wait for current operation to complete: + ```javascript + // Ensure sequential operations + await channel.detach(); + await channel.attach(); + ``` + - Never call conflicting operations simultaneously + +2. **For rapid DOM manipulation** + + - Implement debouncing to reduce operation frequency: + ```javascript + const debouncedAttach = debounce(() => { + channel.attach(); + }, 300); + ``` + +3. **For state-related errors** + + - Check channel state before operations: + ```javascript + if (channel.state === 'attached') { + channel.publish('event', data); + } + ``` + - Monitor connection state to ensure it's active + +4. **For persistent failures** + + - Implement retry with exponential backoff (only for this specific error): + ```javascript + channel.attach((err) => { + if (err && err.code === 90000 && err.statusCode === 409) { + setTimeout(() => channel.attach(), 1000); + } + }); + ``` + +## Automatic Handling + + +Ably SDKs do not automatically retry error 90000. This is an application-level error requiring: +- Proper sequencing of channel operations +- State validation before operations +- Manual retry logic with appropriate delays + +Note: Based on internal discussions, channels often remain functional despite this error appearing in logs. + +## Prevention + + +- **Sequential Operations**: Always await channel operations to complete +- **State Management**: Track channel state in your application +- **Debouncing**: Implement delays for high-frequency scenarios +- **Error Boundaries**: Handle errors gracefully without disrupting user experience + +## SDK Implementation Variations + + +Different Ably SDKs may return different HTTP status codes with error 90000: +- **JavaScript**: 409 for conflicts, 500 for unknown errors, 400 for generic failures +- **iOS/macOS**: Consistently uses 500 +- **Python**: 409 for conflicts +- **Java**: 400 for state failures +- **Go**: No explicit status code + +## Related Resources + +- [Channel lifecycle documentation](https://ably.com/docs/channels#lifecycle) +- [Connection state management](https://ably.com/docs/realtime/connection) +- [Channel attach/detach best practices](https://ably.com/docs/best-practice#channel-lifecycle) +- Related errors: [80000](https://ably.com/docs/errors/80000) (Connection Failed) + +## Need Further Help? + +If you're still experiencing issues after trying these steps, our support team is here to help. + +**Contact Ably Support**: https://ably.com/support + +When contacting support, please provide: +- Your account ID and app ID +- The full error message including error code 90000 +- Steps to reproduce the issue +- Any relevant code snippets (without sensitive credentials) +- The SDK and version you're using + +Our team will help you resolve this issue as quickly as possible. + + + + + + + + + + + + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/90001-channel-operation-failed-invalid-state.mdx b/src/pages/docs/platform/errors/codes/90001-channel-operation-failed-invalid-state.mdx new file mode 100644 index 0000000000..93cf06d352 --- /dev/null +++ b/src/pages/docs/platform/errors/codes/90001-channel-operation-failed-invalid-state.mdx @@ -0,0 +1,243 @@ + + + + + + + + +# Error 90001: Channel operation failed (invalid channel state) + +## What Happened + +You attempted to perform an operation on a channel that isn't in the correct state for that operation. + +## Quick Reference + +| Error Code | HTTP Status | Category | Retryable | +|------------|-------------|----------|-----------| +| 90001 | 400/404/500 | Channel State Error | No - requires state correction | + +## Quick Fix + +- Wait for the channel to reach `attached` state before performing operations +- If the channel is in `failed` state, detach and reattach it +- Use state change listeners to trigger operations at the right time + +## Error Messages + +You may see one of these messages: +- "Channel operation failed (invalid channel state)" +- "Channel operation failed as channel state is {state}" +- "Unable to detach; channel state = failed" +- "Unable to {action} presence channel while in {state} state" +- "Channel not attached" +- "attempted to subscribe while channel is in Failed state" + +The `{state}` placeholder shows the current channel state, and `{action}` shows the operation you attempted. + +## Common Causes + +1. **Publishing before attachment** (60% of cases) + - Attempting to publish messages before the channel is attached + - Not waiting for attachment confirmation + - Racing between channel creation and first operation + + +2. **Operating on failed channels** (25% of cases) + - Trying to use a channel after it entered `failed` state + - Not resetting failed channels before reuse + - Attempting to detach an already failed channel + + +3. **Presence operations in wrong state** (10% of cases) + - Entering presence when channel isn't attached + - Leaving presence during detaching + - Getting presence members on failed channels + + +4. **Device wake/sleep issues** (5% of cases) + - Operations attempted after device wakes from sleep + - Network not ready when SDK attempts operations + - Channels in unexpected states after wake + + +## Resolution Steps + +1. **Check current channel state** + ```javascript + console.log('Channel state:', channel.state); + // States: initialized, attaching, attached, detaching, detached, failed + ``` + + +2. **Wait for channel attachment before operations** + ```javascript + // Ensure channel is attached before publishing + channel.attach((err) => { + if (err) { + console.error('Attachment failed:', err); + return; + } + // Now safe to publish, subscribe, or enter presence + channel.publish('message', 'data'); + }); + ``` + + +3. **Handle failed channels by resetting them** + ```javascript + if (channel.state === 'failed') { + // Detach the failed channel first + channel.detach((err) => { + if (err) { + console.error('Detach failed:', err); + return; + } + // Now reattach for a fresh start + channel.attach((err) => { + if (!err) { + // Channel is ready for operations + channel.publish('message', 'data'); + } + }); + }); + } + ``` + + +4. **Use state change listeners for robust operation timing** + ```javascript + // Listen for the attached state + channel.on('attached', () => { + // Channel is ready, perform your operations here + channel.publish('message', 'data'); + }); + + // Handle state transitions + channel.on((stateChange) => { + console.log('State changed from', stateChange.previous, 'to', stateChange.current); + if (stateChange.current === 'failed') { + // Handle failure - perhaps notify user or attempt recovery + } + }); + ``` + + +5. **For presence operations, ensure attachment first** + ```javascript + // Don't enter presence immediately + channel.attach((err) => { + if (!err) { + channel.presence.enter({ name: 'User' }, (err) => { + if (err) { + console.error('Presence enter failed:', err); + } + }); + } + }); + ``` + + +## Automatic Handling + +Ably SDKs do not automatically retry this error because it indicates a state machine violation that requires explicit correction. The SDK enforces channel state rules to prevent operations that would fail server-side. + + +## Prevention + +- **Always check channel state** before performing operations +- **Use callbacks or promises** that wait for proper attachment +- **Implement state change listeners** to coordinate operations +- **Handle device sleep/wake scenarios** explicitly in mobile apps +- **Test channel failure scenarios** during development + + +## Related Resources + +- [Channel States Documentation](https://ably.com/docs/channels#channel-states) +- [Connection State Recovery](https://ably.com/docs/connect/states) +- [Presence Documentation](https://ably.com/docs/presence) +- Related errors: [90000](https://help.ably.io/error/90000), [90002](https://help.ably.io/error/90002), [90003](https://help.ably.io/error/90003) + +## Need Further Help? + +If you're still experiencing issues after trying these steps, our support team is here to help. + +**Contact Ably Support**: https://ably.com/support + +When contacting support, please provide: +- Your account ID and app ID +- The full error message including error code 90001 +- Steps to reproduce the issue +- Any relevant code snippets (without sensitive credentials) +- The SDK and version you're using + +Our team will help you resolve this issue as quickly as possible. + + + + + + + + + + + + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/90003-unable-to-recover-channel-messages-expired.mdx b/src/pages/docs/platform/errors/codes/90003-unable-to-recover-channel-messages-expired.mdx new file mode 100644 index 0000000000..f89f9cf34e --- /dev/null +++ b/src/pages/docs/platform/errors/codes/90003-unable-to-recover-channel-messages-expired.mdx @@ -0,0 +1,198 @@ + + + + + + + + +# Error 90003: Unable to recover channel (messages expired) + +## What Happened + +Your app attempted to recover a channel after disconnection, but the messages needed for recovery have expired and are no longer available in Ably's message history. + +## Quick Reference + +| Error Code | HTTP Status | Category | Retryable | +|------------|-------------|----------|-----------| +| 90003 | 404 | Channel Error (Recovery) | No - messages are permanently expired | + +## Quick Fix + +- Accept the message gap and let the channel attach without recovery +- Start receiving new messages from the current point forward +- Design your app to handle message gaps gracefully + +## Error Messages + +You may see this error message: +- "Unable to recover channel (messages expired)" + +This appears as a non-fatal error during channel attachment when recovery fails. + +## Common Causes + +1. **Extended disconnection period** (60% of cases) + - Your app was offline longer than your message retention period + - Common with mobile apps that are backgrounded for extended periods + - Network outages lasting beyond retention limits + +2. **High message volume** (25% of cases) + - Too many messages published while disconnected + - Message buffer exceeded storage limits + - High-traffic channels with limited retention + +3. **Account retention limits** (10% of cases) + - Free accounts: 2-minute retention period + - Messages expired based on your plan's limits + - Time-based expiry policies + +4. **Regional sync issues** (5% of cases) + - Rare cases of messages not syncing between regions + - Instance recycling during disconnection + - System maintenance affecting message availability + +## Resolution Steps + +1. **Accept the discontinuity** + - The channel will attach successfully but without historical messages + - Your app will start receiving messages from the current point + - This is a non-fatal error - the connection remains viable + + +2. **Handle the message gap in your application** + ```javascript + channel.on('attached', (stateChange) => { + if (stateChange.reason?.code === 90003) { + // Messages expired - handle the gap + console.log('Channel recovered but some messages were lost'); + // Refresh your UI or request current state from your backend + refreshApplicationState(); + } + }); + ``` + + +3. **Implement state synchronization if needed** + - Request current state from your backend + - Use a separate state channel for critical data + - Don't rely solely on message history for state recovery + + +4. **Review your retention requirements** + - Check your current plan's retention limits at [Ably Dashboard](https://ably.com/dashboard) + - Consider upgrading if you need longer retention periods + - Monitor disconnection patterns in your application + + +## Automatic Handling + +Ably SDKs handle this error automatically: +- The error is marked as non-fatal, so the connection remains active +- The channel will attach successfully without recovery +- New messages will be received normally from the current point +- No automatic retry is performed as the messages are permanently expired + + +## Prevention + +- **Minimize disconnection periods**: Implement aggressive reconnection strategies for critical applications +- **Design for gaps**: Build your application to tolerate message discontinuities +- **Use appropriate retention**: Choose an Ably plan that matches your recovery window needs +- **Implement state channels**: Use dedicated channels for critical state that must survive disconnections +- **Monitor connection health**: Track disconnection duration and patterns + + +## Mobile Considerations + +Mobile applications are particularly susceptible to this error because: +- Apps can be backgrounded for extended periods +- Network switching between WiFi and cellular can cause disconnections +- Battery optimization may terminate connections +- Users may be offline while traveling + +Consider implementing: +- Push notifications to wake the app for critical updates +- Local state caching for offline scenarios +- User notifications when message gaps occur + + +## Related Resources + +- [Channel recovery and resume documentation](https://ably.com/docs/realtime/channels#nonfatal-errors) +- [Message history and retention](https://ably.com/docs/general/history) +- [Connection state recovery](https://ably.com/docs/realtime/connection#connection-state-recovery) +- [Ably pricing and retention limits](https://ably.com/pricing) +- Related error: [90004 - Message limit exceeded](https://help.ably.io/error/90004) + +## Need Further Help? + +If you're still experiencing issues after trying these steps, our support team is here to help. + +**Contact Ably Support**: https://ably.com/support + +When contacting support, please provide: +- Your account ID and app ID +- The full error message including error code 90003 +- Steps to reproduce the issue +- Any relevant code snippets (without sensitive credentials) +- The SDK and version you're using + +Our team will help you resolve this issue as quickly as possible. + + + + + + + + + + + + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/90004-message-limit-exceeded.mdx b/src/pages/docs/platform/errors/codes/90004-message-limit-exceeded.mdx new file mode 100644 index 0000000000..cf194a900b --- /dev/null +++ b/src/pages/docs/platform/errors/codes/90004-message-limit-exceeded.mdx @@ -0,0 +1,175 @@ + + + + + + + + +# Error 90004: Message Limit Exceeded + +## What Happened + +Your channel couldn't recover all missed messages because the number of messages exceeded the system's recovery limit. + +## Quick Reference + +| Error Code | HTTP Status | Category | Retryable | +|------------|-------------|----------|-----------| +| 90004 | 404 | Channel Error (Recovery/Resume) | No - partial recovery succeeded | + +## Quick Fix + +- Channel remains functional with partial message recovery +- Use the History API to retrieve messages beyond the recovery limit +- Reduce rewind parameters to request fewer messages + +## Error Messages + +You may see one of these messages: +- "Unable to recover channel (message limit exceeded)" +- "Channel message limit exceeded [number] bytes" (Ruby SDK specific) + +## Common Causes + +1. **Long disconnection period** (60% of cases) + - Client disconnected for extended time + - More messages accumulated than recovery limit allows + - Example: 20 messages/second × 50 seconds = 1000 messages, but only 100-1000 recoverable + + +2. **Large rewind parameter** (30% of cases) + - Requesting rewind with too many messages + - Rewind timeframe contains more than 100 messages + - Channel has high message volume in requested period + + +3. **High-volume channels** (10% of cases) + - Channels with rapid message rates + - Brief disconnections on busy channels + - Message cache fills quickly during recovery attempt + + +## Resolution Steps + +1. **Continue with partial recovery** + - This is a non-fatal error - your channel remains operational + - The connection is active with the most recent messages available + - The `resumed` flag will be `false` indicating a message gap + + +2. **Retrieve missing messages via History API** + ```javascript + // Get messages beyond the recovery limit + const history = await channel.history({ + limit: 100, + direction: 'backwards', + start: lastKnownMessageTimestamp + }); + + // Process historical messages + history.items.forEach(message => { + processMessage(message); + }); + ``` + + +3. **Adjust recovery parameters** + - For rewind, use smaller time windows or message counts + - Consider implementing pagination for large message sets + - Monitor channel message rates to set appropriate limits + + +4. **Implement message continuity handling** + ```javascript + channel.on('attached', (stateChange) => { + if (!stateChange.resumed) { + // Message continuity lost - fetch missing messages + console.log('Channel attached but message continuity lost'); + fetchMissingMessages(); + } + }); + ``` + + +## Automatic Handling + +Ably SDKs treat this as a non-fatal error: +- Channel attachment proceeds despite the error +- Connection remains active and functional +- Most recent messages (up to limit) are delivered +- The `resumed` flag is set to `false` to indicate message gap + +## Prevention + +- **Monitor disconnection duration**: Be aware that disconnections over 2 minutes may result in message gaps +- **Use appropriate rewind values**: Keep rewind requests under 100 messages +- **Implement fallback strategies**: Always have History API retrieval as backup +- **Consider message rates**: High-volume channels need special handling for recovery + +## Related Resources + +- [Channel options and rewind limits](https://ably.com/docs/channels/options/rewind#limits) +- [History API documentation](https://ably.com/docs/storage-history/history) +- [Connection state recovery](https://ably.com/docs/connect/states) +- Related error: [90003 - Messages Expired](./90003-messages-expired.md) + +## Need Further Help? + +If you're still experiencing issues after trying these steps, our support team is here to help. + +**Contact Ably Support**: https://ably.com/support + +When contacting support, please provide: +- Your account ID and app ID +- The full error message including error code 90004 +- Steps to reproduce the issue +- Any relevant code snippets (without sensitive credentials) +- The SDK and version you're using + +Our team will help you resolve this issue as quickly as possible. + + + + + + + + + + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/90005-channel-recovery-epoch-not-found.mdx b/src/pages/docs/platform/errors/codes/90005-channel-recovery-epoch-not-found.mdx new file mode 100644 index 0000000000..130c881aee --- /dev/null +++ b/src/pages/docs/platform/errors/codes/90005-channel-recovery-epoch-not-found.mdx @@ -0,0 +1,169 @@ + + + + + + + + +# Error 90005: Channel Recovery Epoch Not Found + +## What Happened + +The channel couldn't recover its previous state because the requested recovery point no longer exists on Ably's servers. + +## Quick Reference + +| Error Code | HTTP Status | Category | Retryable | +|------------|-------------|----------|-----------| +| 90005 | 404 | Channel Recovery Error | No - recovery point unavailable | + +## Quick Fix + +- Allow the SDK to handle this automatically - it will reattach without recovery +- Your channel will reconnect with fresh state +- No manual intervention required in most cases + +## Error Messages + +You may see this message: +- "Unable to recover channel (no matching epoch)" + +## Common Causes + +1. **Extended disconnection** (most common) + - Channel was disconnected for longer than the recovery window + - Recovery data has expired on the server + - Typically occurs after prolonged network outages + +2. **Channel with no message history** + - Attempting recovery on a channel that has never had messages + - Clean attachment to empty channels + + +3. **Invalid recovery state** + - Client has outdated or corrupted recovery information + - Recovery point never existed or was from different channel instance + +## Resolution Steps + +1. **Let the SDK handle it automatically** + - Ably SDKs detect this error and automatically reattach without recovery + - The channel continues working but without historical messages + - No code changes needed in most cases + + +2. **If you need message history** + - Use the History API to retrieve missed messages after reattachment + - See [History documentation](https://ably.com/docs/storage-history/history) + + +3. **For critical message continuity** + - Implement client-side state tracking + - Use presence to detect when recovery fails + - Consider using persistent storage for critical data + + +## Automatic Handling + +Ably SDKs automatically handle this error by: +- Detecting the recovery failure +- Reattaching to the channel without recovery +- Emitting an update event to notify your application +- Continuing normal channel operation with fresh state + +The channel remains functional but loses continuity with previous messages. + + +## Prevention + +While this error is handled automatically, you can minimize its occurrence: + +- **Monitor connection state**: Track disconnection duration in your application +- **Store critical state**: Keep important data client-side for reconstruction +- **Use persistent history**: Enable extended history retention for critical channels +- **Implement presence**: Use presence to detect and handle state loss + +## Performance Impact + +This error indicates: +- Loss of message continuity +- Fresh channel state without history +- Potential need to re-establish presence +- No impact on future message delivery + +## Related Resources + +- [Channel state recovery](https://ably.com/docs/realtime/channels#state-recovery) +- [Connection state recovery](https://ably.com/docs/realtime/connection#connection-state-recovery) +- [History API](https://ably.com/docs/storage-history/history) +- [Presence documentation](https://ably.com/docs/presence) +- Related errors: [90003](./90003-messages-expired.md), [90004](./90004-message-limit-exceeded.md), [90006](./90006-unbounded-request.md) + +## Need Further Help? + +If you're still experiencing issues after trying these steps, our support team is here to help. + +**Contact Ably Support**: https://ably.com/support + +When contacting support, please provide: +- Your account ID and app ID +- The full error message including error code 90005 +- Steps to reproduce the issue +- Any relevant code snippets (without sensitive credentials) +- The SDK and version you're using + +Our team will help you resolve this issue as quickly as possible. + + + + + + + + + + + + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/90007-channel-operation-timeout.mdx b/src/pages/docs/platform/errors/codes/90007-channel-operation-timeout.mdx new file mode 100644 index 0000000000..090af84d3b --- /dev/null +++ b/src/pages/docs/platform/errors/codes/90007-channel-operation-timeout.mdx @@ -0,0 +1,173 @@ + + + + + + + + +# Error 90007: Channel operation timeout + +## What happened + +A channel attach or detach operation didn't complete within the configured timeout period, typically 10 seconds. + +## Quick reference + +| Error Code | HTTP Status | Category | Retryable | +|------------|-------------|----------|-----------| +| 90007 | 408 | Channel Operation (Timeout) | Yes - SDK handles automatically | + +## Quick fix + +- For attach timeouts: The SDK automatically retries with exponential backoff +- For detach timeouts: Check connection stability before retrying +- Consider increasing timeout values if your network is slow + +## Error messages + +You may see one of these messages: +- "Channel attach timed out" +- "Channel detach timed out" +- "Channel didn't attach within {timeout}" +- "Channel {attach/detach} operation failed (timed out)" +- "Detach operation timed out" + +## Common causes + +1. **Network connectivity issues** (60% of cases) + - High latency or packet loss + - Unstable network connection + - Firewall or proxy interference + + +2. **Server response delays** (25% of cases) + - Temporary server load + - Regional connectivity issues + - Network path problems + + +3. **Rapid operation sequences** (15% of cases) + - Attempting attach/detach too quickly + - Not waiting for previous operations to complete + - Session timeout handling issues + + +## Resolution steps + +1. **For attach timeout errors** + - The SDK automatically moves the channel to 'suspended' state and retries + - No manual intervention required in most cases + - Monitor the connection state if errors persist + + +2. **For detach timeout errors** + - The channel remains in 'attached' state but reports the error + - You can retry the detach operation after checking connection stability + - Consider if detach is necessary - closing the connection handles channel cleanup automatically + + +3. **Increase timeout values if needed** + ```javascript + const ably = new Ably.Realtime({ + key: 'your-api-key', + realtimeRequestTimeout: 15000, // Increase from default 10000ms + channelRetryTimeout: 20000 // Increase retry timeout + }); + ``` + + +4. **Monitor channel state transitions** + ```javascript + channel.on('suspended', (stateChange) => { + console.log('Channel suspended:', stateChange.reason); + // SDK will automatically retry + }); + ``` + + +## Automatic handling + +Ably SDKs automatically handle this error: +- **For attach timeouts**: Channel moves to 'suspended' state and retries with exponential backoff +- **For detach timeouts**: Error is reported but channel remains functional +- The SDK manages all retry logic - manual intervention is rarely needed + + + +## Prevention + +- Ensure stable network connectivity before channel operations +- Avoid rapid attach/detach cycles +- Wait for operations to complete before initiating new ones +- Use connection close instead of manual channel detach when ending sessions + + +## Related resources + +- [Channel lifecycle documentation](https://ably.com/docs/channels#channel-lifecycle) +- [Connection state management](https://ably.com/docs/connect/states) +- [Timeout configuration options](https://ably.com/docs/connect#timeout-configuration) +- Related errors: [80002](https://help.ably.io/error/80002), [80000](https://help.ably.io/error/80000) + +## Need further help? + +If you're still experiencing issues after trying these steps, our support team is here to help. + +**Contact Ably Support**: https://ably.com/support + +When contacting support, please provide: +- Your account ID and app ID +- The full error message including error code 90007 +- Steps to reproduce the issue +- Any relevant code snippets (without sensitive credentials) +- The SDK and version you're using + +Our team will help you resolve this issue as quickly as possible. + + + + + + + + + + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/90010-channel-limit-exceeded.mdx b/src/pages/docs/platform/errors/codes/90010-channel-limit-exceeded.mdx new file mode 100644 index 0000000000..14871ba1aa --- /dev/null +++ b/src/pages/docs/platform/errors/codes/90010-channel-limit-exceeded.mdx @@ -0,0 +1,195 @@ + + + + + + + + +# Error 90010: Channel limit exceeded + +## What happened? + +You've exceeded the maximum number of channels allowed in a single request or connection. + +## Quick reference + +| Error Code | HTTP Status | Category | Retryable | +|------------|-------------|----------|-----------| +| 90010 | 400 | Channel Error | No - requires splitting request or reducing channels | + +## Quick fix + +- Split bulk operations into batches of 100 channels or fewer +- For connection limits, check your account's channel limit (typically 200-1000) +- Implement pagination or batching for large channel operations + +## Error messages + +You may see one of these messages: +- "Max number of channels permitted in a single bulk presence request (100) exceeded" +- "Max number of channels permitted in a single bulk publish request (100) exceeded" +- "Maximum number of channels per connection 200 exceeded" (limit varies by account) +- "Maximum number of channels per connection 1000 exceeded" (enterprise accounts) + +## Common causes + +1. **Bulk operation exceeds 100 channels** (Most common for batch operations) + + - Attempting bulk publish to more than 100 channels + - Bulk presence request across more than 100 channels + - Not implementing batching for large channel sets + +2. **Per-connection limit exceeded** (Common for realtime connections) + + - Standard accounts: exceeding 200 channels per connection + - Enterprise accounts: exceeding configured limit (often 1000+) + - Incorrectly configured accounts with 50 channel limit + +3. **Rapid channel attachment** (Less common) + + - Attaching to many channels quickly without checking limits + - Not reusing connections efficiently + - Creating new connections unnecessarily + +## Resolution steps + +### For bulk operations (100 channel limit) + +1. **Split your batch requests** + + ```javascript + // Split channels into batches of 100 + const batchSize = 100; + const batches = []; + for (let i = 0; i < channels.length; i += batchSize) { + batches.push(channels.slice(i, i + batchSize)); + } + + // Process each batch + for (const batch of batches) { + await client.request({ + method: 'POST', + path: '/messages', + body: batch + }); + } + ``` + + +2. **Use parallel processing for better performance** + ```javascript + // Process batches in parallel (be mindful of rate limits) + const results = await Promise.all( + batches.map(batch => processBatch(batch)) + ); + ``` + +### For per-connection limits + +1. **Check your account's channel limit** + + - Standard accounts: 200 channels per connection + - Enterprise accounts: Can be configured higher (contact support for increases) + - Verify in your dashboard under account limits + +2. **Optimize channel usage** + - Use channel namespacing to reduce total channels + - Implement channel pooling for efficient reuse + - Consider using wildcards for subscriptions where appropriate + +3. **Distribute across multiple connections** + ```javascript + // Create multiple connections for large channel sets + const connectionsNeeded = Math.ceil(totalChannels / channelLimit); + const connections = Array(connectionsNeeded).fill(null).map(() => + new Ably.Realtime({ key: apiKey }) + ); + ``` + +## Automatic handling + + +This error is not automatically retried by Ably SDKs. The entire batch is rejected without partial processing. Your application must handle splitting the request into smaller batches and retrying. + +## Prevention + +- Implement a channel manager that tracks usage against limits +- Use constants for batch sizes (max 100 for bulk operations) +- Monitor channel usage in your application metrics +- For high-volume applications, contact Ably about enterprise limits + +## Related resources + +- [Channel limits documentation](https://faqs.ably.com/is-there-a-maximum-number-of-channels-per-connection) +- [Batch publishing guide](https://ably.com/docs/api/rest-api#batch-publish) +- [Connection limits](https://ably.com/docs/general/limits) + +## Need further help? + +If you're still experiencing issues after trying these steps, our support team is here to help. + +**Contact Ably Support**: https://ably.com/support + +When contacting support, please provide: +- Your account ID and app ID +- The full error message including error code 90010 +- Steps to reproduce the issue +- Any relevant code snippets (without sensitive credentials) +- The SDK and version you're using + +Our team will help you resolve this issue as quickly as possible. + + + + + + + + + + + + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/90099-generic-discontinuity.mdx b/src/pages/docs/platform/errors/codes/90099-generic-discontinuity.mdx new file mode 100644 index 0000000000..61a6df1cfe --- /dev/null +++ b/src/pages/docs/platform/errors/codes/90099-generic-discontinuity.mdx @@ -0,0 +1,145 @@ + + + + + + + + +# Error 90099: Generic discontinuity + +## What Happened? + +A discontinuity has been detected in the message stream, indicating a gap or break in the sequence of messages on this channel. + +## Quick Reference + +| Error Code | HTTP Status | Category | Retryable | +|------------|-------------|----------|-----------| +| 90099 | 404 | Channel Error (Discontinuity) | No - indicates a gap in message continuity | + +## Quick Fix + +- Assume potential message loss has occurred +- Use the history API to retrieve any missed messages +- Refresh your application state if necessary + +## Error Messages + +You may see one of these messages: +- "Generic discontinuity" + +## Common Causes + +1. **Artificial discontinuity for testing** (Most common) + - Administrative testing of discontinuity handling + - Debug endpoint triggered discontinuity + - Simulated message gap for validation + +2. **Unspecified discontinuity scenario** + - Generic fallback when specific discontinuity type unknown + - Catch-all for unusual continuity breaks + +## Resolution Steps + +1. **Handle the discontinuity in your application** + + - Treat this as an indication that messages may have been missed + - Your application should handle the potential gap in message continuity + +2. **Retrieve missed messages if needed** + + - Use the [history API](https://ably.com/docs/storage-history/history) to fetch messages from before the discontinuity + - Check the channel's continuity flag to confirm the break + +3. **Refresh application state** + + - If your application maintains state based on messages, consider refreshing it + - Re-sync any client-side state that depends on message ordering + +## Automatic Handling + +Ably SDKs automatically detect discontinuities and set the channel's continuity flag to false. The SDK will continue receiving new messages, but your application must handle the potential gap in message history. + +## Understanding Discontinuities + +A discontinuity means there's a break in the continuous flow of messages. This can happen due to: +- Network interruptions lasting longer than connection recovery windows +- Server-side message expiration +- Testing and debugging scenarios +- Unusual edge cases in message delivery + +When a discontinuity occurs, you cannot rely on having received all messages in sequence. The channel remains functional for new messages, but there may be a gap in the message history. + +## Related Resources + +- [Message continuity documentation](https://ably.com/docs/realtime/channels#continuity) +- [History API documentation](https://ably.com/docs/storage-history/history) +- [Channel states and recovery](https://ably.com/docs/realtime/channels#states) +- Related errors: [90003](https://help.ably.io/error/90003) (Messages expired), [90004](https://help.ably.io/error/90004) (Message limit exceeded) + +## Need Further Help? + +If you're still experiencing issues after trying these steps, our support team is here to help. + +**Contact Ably Support**: https://ably.com/support + +When contacting support, please provide: +- Your account ID and app ID +- The full error message including error code 90099 +- Steps to reproduce the issue +- Any relevant code snippets (without sensitive credentials) +- The SDK and version you're using + +Our team will help you resolve this issue as quickly as possible. + + + + + + + + + + + + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/91000-presence-requires-client-id.mdx b/src/pages/docs/platform/errors/codes/91000-presence-requires-client-id.mdx new file mode 100644 index 0000000000..f211e15055 --- /dev/null +++ b/src/pages/docs/platform/errors/codes/91000-presence-requires-client-id.mdx @@ -0,0 +1,180 @@ + + + + + + + + +# Error 91000: Presence requires client ID + +## What Happened + +You attempted to enter, update, or leave a presence channel without having a client ID configured for your connection. + +## Quick Reference + +| Error Code | HTTP Status | Category | Retryable | +|------------|-------------|----------|-----------| +| 91000 | 400 | Client Error (Presence) | No - requires setting client ID | + +## Quick Fix + +- Set a client ID when initializing your Ably client +- Or configure client ID in your token authentication +- Or use JWT authentication with a client ID claim + +## Error Messages + +You may see one of these messages: +- "unable to enter presence channel (no clientId)" +- "Invalid attempt to enter with no clientId" +- "Unable to enter create presence message without a client_id" + +## Common Causes + +1. **No client ID configured** (90% of cases) + - Creating an Ably client without specifying a client ID + - Using basic authentication without setting client ID + - Missing client ID in token parameters + + +2. **Anonymous connection attempting presence** (8% of cases) + - Default connections don't have client IDs + - Quick-start implementations often miss this requirement + - Demo applications without proper authentication setup + + +3. **Client ID lost during authentication renewal** (2% of cases) + - Token renewal didn't include client ID + - JWT token missing client ID claim + + +## Resolution Steps + +1. **Set client ID in client options** + ```javascript + const ably = new Ably.Realtime({ + key: 'your-api-key', + clientId: 'unique-user-id' // Add this line + }); + ``` + + +2. **Configure client ID via token authentication** + ```javascript + const tokenParams = { + clientId: 'unique-user-id' + }; + const token = await ably.auth.requestToken(tokenParams); + ``` + + +3. **Use JWT with client ID claim** + - Ensure your JWT includes a client ID in the token claims + - The JWT should be generated server-side with the appropriate client ID + + +4. **Verify client ID is set** + ```javascript + // Check if client ID is configured + console.log('Client ID:', ably.auth.clientId); + + // Only attempt presence if client ID exists + if (ably.auth.clientId) { + await channel.presence.enter(); + } + ``` + + +## Automatic Handling + +This is a client error that will not be automatically retried. You must configure a client ID before the presence operation will succeed. + +## Prevention + +- **Always set client ID for presence-enabled applications**: Configure during initialization or authentication +- **Use meaningful identifiers**: User IDs, usernames, or session IDs work well +- **Maintain consistency**: Use the same client ID across reconnections for the same user +- **Validate before presence operations**: Check that client ID exists before calling presence methods + + +## Security Considerations + +- **Use token authentication for production**: Basic authentication with client ID can be spoofed +- **Server-side validation**: Generate tokens server-side to ensure client ID authenticity +- **Avoid sensitive data**: Don't use personal information as client IDs +- **Unique identifiers**: Ensure each user has a unique client ID to prevent conflicts + + +## Related Resources + +- [Ably Presence documentation](https://ably.com/docs/presence) +- [Identified clients guide](https://ably.com/docs/auth/identified-clients) +- [Token authentication](https://ably.com/docs/auth/token) +- Related errors: [91001](./91001-invalid-presence-state.md), [91003](./91003-presence-member-limit.md) + +## Need Further Help? + +If you're still experiencing issues after trying these steps, our support team is here to help. + +**Contact Ably Support**: https://ably.com/support + +When contacting support, please provide: +- Your account ID and app ID +- The full error message including error code 91000 +- Steps to reproduce the issue +- Any relevant code snippets (without sensitive credentials) +- The SDK and version you're using + +Our team will help you resolve this issue as quickly as possible. + + + + + + + + + + + + \ No newline at end of file From 562936b9c6bce5b53889aee6ab2e6166e4fcd9f6 Mon Sep 17 00:00:00 2001 From: Matthew O'Riordan Date: Thu, 21 Aug 2025 20:08:57 +0100 Subject: [PATCH 2/6] Add missing error codes --- .../errors/codes/40011-stale-ring-state.mdx | 4 +- .../errors/codes/40012-invalid-client-id.mdx | 61 ++++- ...40013-invalid-message-data-or-encoding.mdx | 201 +++++++++++++++ .../errors/codes/40014-resource-disposed.mdx | 181 +++++++++++++ .../errors/codes/40015-invalid-device-id.mdx | 165 ++++++++++++ .../40017-unsupported-protocol-version.mdx | 161 ++++++++++++ .../codes/40018-delta-decode-failure.mdx | 179 +++++++++++++ .../errors/codes/40019-missing-plugin.mdx | 231 +++++++++++++++++ .../codes/40020-batch-partial-failure.mdx | 224 +++++++++++++++++ ...invalid-resource-or-deprecated-feature.mdx | 185 ++++++++++++++ .../codes/40023-protocol-version-required.mdx | 169 +++++++++++++ .../codes/40024-channel-mode-required.mdx | 174 +++++++++++++ .../codes/40030-invalid-publish-request.mdx | 174 +++++++++++++ .../errors/codes/40031-invalid-message-id.mdx | 202 +++++++++++++++ .../codes/40032-invalid-extras-field.mdx | 209 +++++++++++++++ .../codes/40099-internal-testing-error.mdx | 131 ++++++++++ .../codes/40100-unauthorized-access.mdx | 187 ++++++++++++++ .../codes/40101-invalid-credentials.mdx | 143 +++++++++-- .../codes/40102-incompatible-credentials.mdx | 237 +++++++++++++++++ .../codes/40103-basic-auth-requires-tls.mdx | 170 +++++++++++++ .../codes/40104-timestamp-not-current.mdx | 203 +++++++++++++++ ...106-missing-authentication-credentials.mdx | 222 ++++++++++++++++ .../errors/codes/40113-account-blocked.mdx | 176 +++++++++++++ .../40115-account-request-limit-exceeded.mdx | 183 ++++++++++++++ .../40121-token-revocation-not-enabled.mdx | 154 ++++++++++++ .../errors/codes/40130-key-removed.mdx | 177 +++++++++++++ .../errors/codes/40131-key-revoked.mdx | 202 +++++++++++++++ .../errors/codes/40132-api-key-expired.mdx | 211 ++++++++++++++++ ...3-token-revocation-authorization-error.mdx | 36 +-- .../codes/40140-token-error-unspecified.mdx | 118 +++++++-- .../errors/codes/40142-token-expired.mdx | 22 +- .../codes/40144-invalid-jwt-token-format.mdx | 37 ++- .../codes/40146-unsupported-token-claims.mdx | 143 ++++++----- .../40149-token-error-range-boundary.mdx | 10 +- .../codes/90099-generic-discontinuity.mdx | 23 +- .../91000-presence-requires-client-id.mdx | 78 ++++-- .../91001-presence-channel-invalid-state.mdx | 238 ++++++++++++++++++ .../91004-presence-auto-reenter-failed.mdx | 224 +++++++++++++++++ .../91005-presence-state-out-of-sync.mdx | 201 +++++++++++++++ .../91100-member-implicitly-left-presence.mdx | 181 +++++++++++++ .../92000-liveobjects-validation-error.mdx | 171 +++++++++++++ .../errors/codes/92001-conflicting-usage.mdx | 205 +++++++++++++++ .../codes/92002-cipher-algorithm-mismatch.mdx | 168 +++++++++++++ .../codes/92003-cipher-decryption-failed.mdx | 161 ++++++++++++ ...04-dual-purpose-cipher-or-object-error.mdx | 222 ++++++++++++++++ .../codes/92005-duplicate-context-error.mdx | 217 ++++++++++++++++ .../codes/92100-encoding-value-too-long.mdx | 178 +++++++++++++ ...3001-annotations-channel-state-invalid.mdx | 219 ++++++++++++++++ ...3002-mutable-messages-feature-required.mdx | 162 ++++++++++++ 49 files changed, 7768 insertions(+), 162 deletions(-) create mode 100644 src/pages/docs/platform/errors/codes/40013-invalid-message-data-or-encoding.mdx create mode 100644 src/pages/docs/platform/errors/codes/40014-resource-disposed.mdx create mode 100644 src/pages/docs/platform/errors/codes/40015-invalid-device-id.mdx create mode 100644 src/pages/docs/platform/errors/codes/40017-unsupported-protocol-version.mdx create mode 100644 src/pages/docs/platform/errors/codes/40018-delta-decode-failure.mdx create mode 100644 src/pages/docs/platform/errors/codes/40019-missing-plugin.mdx create mode 100644 src/pages/docs/platform/errors/codes/40020-batch-partial-failure.mdx create mode 100644 src/pages/docs/platform/errors/codes/40022-invalid-resource-or-deprecated-feature.mdx create mode 100644 src/pages/docs/platform/errors/codes/40023-protocol-version-required.mdx create mode 100644 src/pages/docs/platform/errors/codes/40024-channel-mode-required.mdx create mode 100644 src/pages/docs/platform/errors/codes/40030-invalid-publish-request.mdx create mode 100644 src/pages/docs/platform/errors/codes/40031-invalid-message-id.mdx create mode 100644 src/pages/docs/platform/errors/codes/40032-invalid-extras-field.mdx create mode 100644 src/pages/docs/platform/errors/codes/40099-internal-testing-error.mdx create mode 100644 src/pages/docs/platform/errors/codes/40100-unauthorized-access.mdx create mode 100644 src/pages/docs/platform/errors/codes/40102-incompatible-credentials.mdx create mode 100644 src/pages/docs/platform/errors/codes/40103-basic-auth-requires-tls.mdx create mode 100644 src/pages/docs/platform/errors/codes/40104-timestamp-not-current.mdx create mode 100644 src/pages/docs/platform/errors/codes/40106-missing-authentication-credentials.mdx create mode 100644 src/pages/docs/platform/errors/codes/40113-account-blocked.mdx create mode 100644 src/pages/docs/platform/errors/codes/40115-account-request-limit-exceeded.mdx create mode 100644 src/pages/docs/platform/errors/codes/40121-token-revocation-not-enabled.mdx create mode 100644 src/pages/docs/platform/errors/codes/40130-key-removed.mdx create mode 100644 src/pages/docs/platform/errors/codes/40131-key-revoked.mdx create mode 100644 src/pages/docs/platform/errors/codes/40132-api-key-expired.mdx create mode 100644 src/pages/docs/platform/errors/codes/91001-presence-channel-invalid-state.mdx create mode 100644 src/pages/docs/platform/errors/codes/91004-presence-auto-reenter-failed.mdx create mode 100644 src/pages/docs/platform/errors/codes/91005-presence-state-out-of-sync.mdx create mode 100644 src/pages/docs/platform/errors/codes/91100-member-implicitly-left-presence.mdx create mode 100644 src/pages/docs/platform/errors/codes/92000-liveobjects-validation-error.mdx create mode 100644 src/pages/docs/platform/errors/codes/92001-conflicting-usage.mdx create mode 100644 src/pages/docs/platform/errors/codes/92002-cipher-algorithm-mismatch.mdx create mode 100644 src/pages/docs/platform/errors/codes/92003-cipher-decryption-failed.mdx create mode 100644 src/pages/docs/platform/errors/codes/92004-dual-purpose-cipher-or-object-error.mdx create mode 100644 src/pages/docs/platform/errors/codes/92005-duplicate-context-error.mdx create mode 100644 src/pages/docs/platform/errors/codes/92100-encoding-value-too-long.mdx create mode 100644 src/pages/docs/platform/errors/codes/93001-annotations-channel-state-invalid.mdx create mode 100644 src/pages/docs/platform/errors/codes/93002-mutable-messages-feature-required.mdx diff --git a/src/pages/docs/platform/errors/codes/40011-stale-ring-state.mdx b/src/pages/docs/platform/errors/codes/40011-stale-ring-state.mdx index 4d14b3ca7e..1a6438f851 100644 --- a/src/pages/docs/platform/errors/codes/40011-stale-ring-state.mdx +++ b/src/pages/docs/platform/errors/codes/40011-stale-ring-state.mdx @@ -1,7 +1,7 @@ - + - + - + # Error 40012: Invalid client ID @@ -27,6 +27,7 @@ Your request contains a client ID that doesn't meet Ably's validation requiremen - Remove the client ID from your message if it's already set via authentication - Ensure your client ID is a non-empty string (not "" or null in messages) - Don't use "*" as a client ID except in token parameters for wildcard capability +- For Laravel Echo users: Check compatibility with Pusher protocol adapter ## Error Messages @@ -39,12 +40,16 @@ You may see one of these messages: - "Incompatible clientId specified in message" - "clientId must be specified to enter or leave a presence channel" - "invalid clientId; must be base64 encoded if passed by header" +- "Malformed message; no clientId in message or inferred from connection" +- "Invalid client ID provided" +- "Wildcard client_id is reserved and cannot be used when publishing messages" ## Common Causes 1. **Empty string as client ID** (35% of cases) - Using "" instead of a proper string value - Not setting client ID when required for presence + - Empty string in token requests 2. **Client ID mismatch** (30% of cases) @@ -56,6 +61,7 @@ You may see one of these messages: 3. **Wildcard "*" misuse** (20% of cases) - Using "*" as a regular client ID instead of in token parameters - Attempting to initialize REST client with wildcard client ID + - Wildcard in request headers or URLs 4. **Missing client ID for presence** (10% of cases) @@ -66,6 +72,7 @@ You may see one of these messages: 5. **Invalid type or encoding** (5% of cases) - Client ID is not a string or null - Missing base64 encoding when passed via header + - Non-string values in JWT tokens ## Resolution Steps @@ -73,6 +80,15 @@ You may see one of these messages: 1. **For empty client ID errors** - Provide a non-empty string for your client ID - If client ID is optional in your context, use null instead of "" + ```javascript + // ❌ Wrong: Empty string + const ably = new Ably.Realtime({ clientId: '' }); + + // ✅ Correct: Valid string or null + const ably = new Ably.Realtime({ clientId: 'user-123' }); + // or + const ably = new Ably.Realtime({ /* no clientId */ }); + ``` 2. **For client ID mismatch errors** @@ -111,7 +127,7 @@ You may see one of these messages: ```javascript // ❌ Wrong: No client ID for presence const ably = new Ably.Realtime({ key: 'your-api-key' }); - channel.presence.enter(); // Will fail + channel.presence.enter(); // Will fail with 40012 // ✅ Correct: Client ID configured const ably = new Ably.Realtime({ @@ -144,11 +160,28 @@ You may see one of these messages: 6. **For header encoding issues** - When using X-Ably-Clientid header, base64 encode the value - Alternatively, use query parameter clientId (no encoding needed) + ```bash + # ❌ Wrong: Plain text in header + curl -H "X-Ably-Clientid: user-123" ... + + # ✅ Correct: Base64 encoded + curl -H "X-Ably-Clientid: dXNlci0xMjM=" ... + + # ✅ Or use query parameter + curl "https://rest.ably.io/channels/test?clientId=user-123" ... + ``` +7. **For Laravel Echo with Pusher Protocol** + - If using Laravel Echo with Ably's Pusher protocol adapter and experiencing presence issues: + - Ensure your client ID format is compatible with Pusher protocol expectations + - Consider using native Ably SDK instead of Pusher protocol adapter for presence channels + - Verify your Laravel Echo configuration matches Ably's requirements + + ## Automatic Handling -This is a client error that will not be automatically retried. You must fix the client ID configuration issue before the operation will succeed. +This is a client error that will not be automatically retried. You must fix the client ID configuration issue before the operation will succeed. The SDK will not attempt to recover from this error as it indicates a configuration problem that requires manual intervention. ## Prevention @@ -157,6 +190,18 @@ This is a client error that will not be automatically retried. You must fix the - **Tokens**: Include clientId in token generation for user-specific connections - **Presence**: Always configure clientId before attempting presence operations - **Validation**: Ensure clientId is either a non-empty string or null (not undefined or other types) +- **Laravel Echo**: Test presence channels thoroughly when using Pusher protocol adapter + +## SDK-Specific Behaviors + +Different Ably SDKs may show slightly different error messages: +- **JavaScript**: Most comprehensive validation with specific messages for each scenario +- **Java**: Uses "Incompatible clientId" terminology +- **Python**: Includes actual values in error messages for debugging +- **Ruby**: May throw IncompatibleClientId exception +- **PHP**: Specifically validates against wildcard in REST context +- **.NET**: Reports "Invalid client ID in API key" for parsing errors +- **Go**: Provides detailed mismatch information ## Related Resources @@ -164,6 +209,7 @@ This is a client error that will not be automatically retried. You must fix the - [Client ID explained](https://ably.com/docs/auth/identified-clients) - [Presence documentation](https://ably.com/docs/presence) - [Token authentication](https://ably.com/docs/auth/token) +- [Laravel Echo integration](https://ably.com/docs/general/laravel-echo) ## Need Further Help? @@ -177,6 +223,7 @@ When contacting support, please provide: - Steps to reproduce the issue - Any relevant code snippets (without sensitive credentials) - The SDK and version you're using +- If using Laravel Echo, your configuration details Our team will help you resolve this issue as quickly as possible. @@ -188,11 +235,13 @@ Our team will help you resolve this issue as quickly as possible. - Analysis File: https://github.com/ably/ably-os/blob/main/output/error-codes/research/40012-analysis.md - Knowledge File: https://github.com/ably/ably-os/blob/main/output/error-codes/research/40012-knowledge.md - Editorial Notes: https://github.com/ably/ably-os/blob/main/src/prompts/errors/editorial-notes.md -- Existing Documentation: None found +- Existing Documentation: https://github.com/ably/docs/blob/main/src/pages/docs/platform/errors/codes/40012-invalid-client-id.mdx (enhanced from existing) --> diff --git a/src/pages/docs/platform/errors/codes/40013-invalid-message-data-or-encoding.mdx b/src/pages/docs/platform/errors/codes/40013-invalid-message-data-or-encoding.mdx new file mode 100644 index 0000000000..86bb1781af --- /dev/null +++ b/src/pages/docs/platform/errors/codes/40013-invalid-message-data-or-encoding.mdx @@ -0,0 +1,201 @@ + + + + + + + + +# Error 40013: Invalid message data or encoding + +## What Happened + +The SDK cannot encode or decode your message because the data type is unsupported or the encoding process failed. + +## Quick Reference + +| Error Code | HTTP Status | Category | Retryable | +|------------|-------------|----------|-----------| +| 40013 | 400 | Client Error (Message Processing) | No - requires fixing the data format | + +## Quick Fix + +- Ensure message data is a string, buffer, JSON-serializable object, or array +- For encrypted channels, verify cipher configuration is consistent across clients +- Consider marshalling complex data as JSON before publishing + +## Error Messages + +You may see one of these messages: +- "Data type is unsupported" +- "Invalid message data or encoding" +- "The single-argument form of publish() expects a message object or an array of message objects" +- "Map value data type is unsupported" (LiveObjects) +- "Invalid data type for 'base64' decoding" +- "Invalid data type for 'json' decoding" +- "decrypt failed" +- "Error processing the {encoding} encoding, decoder returned '{error}'" + +## Common Causes + +1. **Unsupported data types** (60% of cases) + + - Publishing objects that aren't JSON-serializable + - Using LiveObjects with unsupported value types + - Passing wrong argument types to publish() + +2. **Encryption/decryption failures** (30% of cases) + + - Cipher configuration mismatch between clients + - Decryption failures after channel idle periods + - Race conditions with encryption key handling + +3. **Encoding chain failures** (10% of cases) + + - Invalid base64 data + - Malformed JSON strings + - UTF-8 encoding of binary data + +## Resolution Steps + +1. **Validate your message data type** + + + Supported types vary by SDK: + - **JavaScript**: String, Buffer, JSON-serializable objects/arrays + - **Ruby**: String, Hash, Array, or nil + - **iOS/macOS**: NSString, NSData, NSArray, NSDictionary + - **Java**: String, byte[], JsonElement + + For complex objects, serialize to JSON first: + ```javascript + // ❌ Wrong: Publishing non-serializable object + channel.publish('update', myComplexObject); + + // ✅ Correct: Serialize to JSON first + channel.publish('update', JSON.stringify(myComplexObject)); + ``` + + +2. **Fix publish() method arguments** (JavaScript SDKs) + + + ```javascript + // ❌ Wrong: Invalid single argument + channel.publish('not-a-message-object'); + + // ✅ Correct: Use message object + channel.publish({ name: 'event', data: 'payload' }); + + // ✅ Correct: Or use name and data arguments + channel.publish('event', 'payload'); + ``` + + +3. **Verify encryption configuration** + + + If using encrypted channels, ensure all clients use identical cipher configuration: + ```javascript + // All clients must use the same key and options + const cipherKey = await generateKey(); + const channel = ably.channels.get('encrypted-channel', { + cipher: { key: cipherKey } + }); + ``` + + +4. **Handle LiveObjects data types** + + + For LiveObjects, only use supported types: + ```javascript + // ❌ Wrong: Unsupported type + liveMap.set('key', new Date()); + + // ✅ Correct: Use supported types + liveMap.set('key', Date.now()); // number + liveMap.set('data', { name: 'value' }); // object + ``` + + +## Automatic Handling + +This is a client error that will not be automatically retried. The SDK cannot recover from invalid data types or encoding failures - you must fix the data format or configuration before the operation will succeed. + +## Prevention + +- Always validate data types before publishing +- Use explicit JSON serialization for complex objects +- Maintain consistent cipher configuration across all clients +- Test encoding/decoding with your specific data types in development +- Enable verbose logging to capture full error context during debugging + +## Related Resources + +- [Message encoding documentation](https://ably.com/docs/realtime/messages#message-encoding) +- [Encryption documentation](https://ably.com/docs/realtime/encryption) +- [LiveObjects documentation](https://ably.com/docs/products/liveobjects) +- Related errors: [40000](./40000-bad-request.md) (general bad request), [92001-92005](./92001-encryption-error.md) (encryption-specific errors) + +## Need Further Help? + +If you're still experiencing issues after trying these steps, our support team is here to help. + +**Contact Ably Support**: https://ably.com/support + +When contacting support, please provide: +- Your account ID and app ID +- The full error message including error code 40013 +- Steps to reproduce the issue +- Any relevant code snippets (without sensitive credentials) +- The SDK and version you're using + +Our team will help you resolve this issue as quickly as possible. + + + + + + + + + + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/40014-resource-disposed.mdx b/src/pages/docs/platform/errors/codes/40014-resource-disposed.mdx new file mode 100644 index 0000000000..8291a38cf9 --- /dev/null +++ b/src/pages/docs/platform/errors/codes/40014-resource-disposed.mdx @@ -0,0 +1,181 @@ + + + + + + + + +# Error 40014: Resource disposed + +## What Happened + +The operation failed because the requested resource (such as a channel, connection, or internal component) has already been disposed or closed. + +## Quick Reference + +| Error Code | HTTP Status | Category | Retryable | +|------------|-------------|----------|-----------| +| 40014 | 400 | Client Error (Resource Management) | Yes - after creating new resource | + +## Quick Fix + +- Create a new instance of the resource (channel, connection) and retry the operation +- Implement retry logic with exponential backoff for transient disposal errors +- Ensure you're not holding references to disposed resources + + +## Error Messages + +You may see one of these messages: +- "Resource disposed" +- "StateCache has been disposed" +- "PresenceMap has been disposed" +- "Unable to perform operation; resource disposed" +- "Redis client disposed" +- "Attachment disposed during preparation" +- "Channel disposed" + + +## Common Causes + +1. **Channel lifecycle issues** (60% of cases) + - Channel was disposed while operations were in progress + - Attach request was superseded by a detach request + - Channel attachment was aborted before completion + + +2. **Service deployment or restart** (25% of cases) + - Ably service deployments causing temporary resource disposal + - Coordinator relocation during channel setup + - Connection recycling during maintenance + + +3. **High-volume scenarios** (15% of cases) + - Redis connection disposal during high traffic + - Presence validation occurring on disposed resources + - Message rule operations on disposed ClusteredKeySet + + +## Resolution Steps + +1. **Implement retry logic for publish operations** + + ```javascript + const publishWithRetry = () => { + channel.publish(name, data, (err) => { + if (err && err.code === 40014) { + // Resource was disposed, retry the operation + publishWithRetry(); + return; + } + // Handle other errors or success + }); + }; + ``` + +2. **For channel attachment errors** + - Detach and re-attach the channel + - Create a new channel instance if detach fails + - Ensure proper cleanup of old channel references + + +3. **For connection-level issues** + - Create a new Ably client connection + - Re-establish all channel subscriptions + - Restore presence state if applicable + +4. **Monitor and track occurrences** + - Track frequency of 40014 errors as a system health indicator + - High volumes (>8 errors/second) may indicate infrastructure issues + - Contact support if errors persist at high volume + + +## Automatic Handling + +This error indicates a disposed resource and requires application-level handling. Ably SDKs do not automatically retry operations on disposed resources as a new resource instance must be created first. + + +## Prevention + +- Properly manage resource lifecycles in your application +- Avoid holding long-lived references to channels or connections +- Implement graceful shutdown sequences for resources +- Use connection state callbacks to track resource availability + + +## Performance Impact + +While this error is typically transient and recoverable: +- May cause temporary message delivery delays during retry +- High volumes can indicate service degradation +- Not typically user-facing unless retry logic is missing + + +## Related Resources + +- [Channel lifecycle documentation](https://ably.com/docs/channels#attach-detach) +- [Connection state management](https://ably.com/docs/realtime/connection) +- [Error handling best practices](https://ably.com/docs/best-practice#error-handling) + +## Need Further Help? + +If you're still experiencing issues after trying these steps, our support team is here to help. + +**Contact Ably Support**: https://ably.com/support + +When contacting support, please provide: +- Your account ID and app ID +- The full error message including error code 40014 +- Steps to reproduce the issue +- Any relevant code snippets (without sensitive credentials) +- The SDK and version you're using + +Our team will help you resolve this issue as quickly as possible. + + + + + + + + + + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/40015-invalid-device-id.mdx b/src/pages/docs/platform/errors/codes/40015-invalid-device-id.mdx new file mode 100644 index 0000000000..6d6a373c1b --- /dev/null +++ b/src/pages/docs/platform/errors/codes/40015-invalid-device-id.mdx @@ -0,0 +1,165 @@ + + + + + + + + +# Error 40015: Invalid device ID + +## What Happened + +The device ID provided in your push notification registration request doesn't meet the required format - it must be a non-empty string. + +## Quick Reference + +| Error Code | HTTP Status | Category | Retryable | +|------------|-------------|----------|-----------| +| 40015 | 400 | Client Error (Push Notifications) | No - requires fixing the device ID format | + +## Quick Fix + +- Ensure your device ID is a non-empty string value +- Remove any non-string types (numbers, objects, arrays) +- Check that the device ID isn't an empty string + +## Error Messages + +You'll see this message: +- "Invalid deviceId" + +## Common Causes + +1. **Non-string device ID** (60% of cases) + - Passing a number instead of string + - Passing an object or array + - Passing null or undefined + + +2. **Empty string device ID** (30% of cases) + - Device ID is present but empty (`""`) + - Whitespace-only string + + +3. **Missing device ID in registration** (10% of cases) + - DeviceDetails object missing the ID property + - Attempting to register without proper device identification + + +## Resolution Steps + +1. **Verify device ID type and content** + - Ensure the device ID is a string type + - Confirm it contains actual characters (not empty) + + +2. **Check your DeviceDetails object structure** + ```javascript + // ❌ Wrong: Non-string device ID + const deviceDetails = { + id: 12345 // Number, not string + }; + + // ❌ Wrong: Empty device ID + const deviceDetails = { + id: "" // Empty string + }; + + // ✅ Correct: Valid device ID + const deviceDetails = { + id: "device-abc-123" // Non-empty string + }; + ``` + + +3. **Review the push registration parameters** + - When registering for push notifications, provide either `deviceId` OR `clientId`, not both + - If you receive error 40018, you're providing both parameters + - If you receive error 40019, you're providing neither parameter + + +4. **Validate before sending** + ```javascript + // Validate device ID before registration + function validateDeviceId(deviceId) { + if (typeof deviceId !== 'string' || deviceId === '') { + throw new Error('Device ID must be a non-empty string'); + } + return true; + } + ``` + + +## Automatic Handling + +This is a client error that will not be automatically retried. You must fix the device ID format before the registration will succeed. + +## Related Resources +- [Push Notifications Documentation](https://ably.com/docs/push) +- [DeviceDetails API Reference](https://ably.com/docs/api/rest-sdk/push-admin#device-details) +- Related errors: [40012 (Invalid clientId)](https://help.ably.io/error/40012), [40018 (Both IDs provided)](https://help.ably.io/error/40018), [40019 (Neither ID provided)](https://help.ably.io/error/40019) + +## Need Further Help? + +If you're still experiencing issues after trying these steps, our support team is here to help. + +**Contact Ably Support**: https://ably.com/support + +When contacting support, please provide: +- Your account ID and app ID +- The full error message including error code 40015 +- Steps to reproduce the issue +- Any relevant code snippets (without sensitive credentials) +- The SDK and version you're using + +Our team will help you resolve this issue as quickly as possible. + + + + + + + + + + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/40017-unsupported-protocol-version.mdx b/src/pages/docs/platform/errors/codes/40017-unsupported-protocol-version.mdx new file mode 100644 index 0000000000..53adfb8815 --- /dev/null +++ b/src/pages/docs/platform/errors/codes/40017-unsupported-protocol-version.mdx @@ -0,0 +1,161 @@ + + + + + + + + +# Error 40017: Unsupported protocol version + +## What Happened + +The request did not specify a protocol version or provided an invalid version in the request parameters. + +## Quick Reference + +| Error Code | HTTP Status | Category | Retryable | +|------------|-------------|----------|-----------| +| 40017 | 400 | Client Error (Protocol) | No - requires fixing request parameters | + +## Quick Fix + +- Add `?v=1.1` or higher to SSE connection requests +- Ensure WebSocket connections use valid API versions +- Update to latest SDK version (SDK users won't see this error) + +## Error Messages + +You may see one of these messages: +- "Stateless connections must specify a protocol version (e.g. ?v=1.1)" +- "Invalid api version specified: [version]. See https://help.ably.io/error/40017" +- "Unsupported protocol version" + +## Common Causes + +1. **Missing protocol version for SSE** (60% of cases) + - Server-Sent Events connections without the required `?v=` parameter + - Direct API calls to SSE endpoints without version specification + + +2. **Invalid version format** (25% of cases) + - Incorrectly formatted version strings (e.g., "3.0" when not supported) + - Using version numbers not recognized by the platform + + +3. **Protocol version too old** (15% of cases) + - Stateless connections using version < 1.1 + - Using deprecated protocol versions + + +## Resolution Steps + +1. **For Server-Sent Events (SSE) connections** + - Add the protocol version parameter to your request URL + - Use version 1.1 or higher for stateless connections + - Example: `https://rest.ably.io/event-stream?v=1.1&key=YOUR_KEY` + + +2. **For WebSocket connections** + - Verify the API version specified in your connection parameters + - Check Ably documentation for supported version numbers + - Remove or correct any invalid version parameters + + +3. **For SDK users** + - Update to the latest SDK version + - SDKs automatically handle protocol versioning + - You should not encounter this error with properly configured SDKs + + +4. **Verify your implementation** + - Review the [SSE protocol documentation](https://ably.com/docs/protocols/sse) + - Check the [API versioning guide](https://ably.com/docs/api-versioning) + - Ensure all manual API calls include proper version parameters + +## Automatic Handling + +Ably SDKs automatically handle protocol versioning. This error only occurs when: +- Making direct API calls without an SDK +- Using custom implementations that bypass SDK version management +- Manually constructing SSE or WebSocket connection URLs + +SDK users are protected from this error as the SDK negotiates the appropriate protocol version automatically. + + +## Prevention + +- **Always use official SDKs** when possible for automatic version handling +- **Include version parameters** in all manual SSE connection requests +- **Test protocol compatibility** before deploying custom implementations +- **Keep SDKs updated** to ensure support for latest protocol versions + + +## Related Resources + +- [SSE Protocol Documentation](https://ably.com/docs/protocols/sse) +- [Ably Protocol Specification](https://github.com/ably/specification) +- [Connection State Management](https://ably.com/docs/realtime/connection) +- Related errors: [80015](./80015-incompatible-connection-parameters.md) (connection parameter issues), [40021](./40021-newer-platform-version-required.md) (feature version requirements) + +## Need Further Help? + +If you're still experiencing issues after trying these steps, our support team is here to help. + +**Contact Ably Support**: https://ably.com/support + +When contacting support, please provide: +- Your account ID and app ID +- The full error message including error code 40017 +- Steps to reproduce the issue +- Any relevant code snippets (without sensitive credentials) +- The SDK and version you're using + +Our team will help you resolve this issue as quickly as possible. + + + + + + + + + + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/40018-delta-decode-failure.mdx b/src/pages/docs/platform/errors/codes/40018-delta-decode-failure.mdx new file mode 100644 index 0000000000..ce86598c74 --- /dev/null +++ b/src/pages/docs/platform/errors/codes/40018-delta-decode-failure.mdx @@ -0,0 +1,179 @@ + + + + + + + + +# Error 40018: Delta decode failure + +## What Happened + +The SDK couldn't decode a delta-compressed message, which means the channel needs to reattach to restore message continuity. + +## Quick Reference + +| Error Code | HTTP Status | Category | Retryable | +|------------|-------------|----------|-----------| +| 40018 | 400 | Client Error (Message Processing) | Yes - SDK handles recovery automatically | + +## Quick Fix + +- No immediate action required - Ably SDKs automatically recover +- Monitor for repeated occurrences which may indicate network issues +- Check SDK logs to verify the recovery process completed + +## Error Messages + +You may see one of these messages: +- "Unable to decode message; channel attachment no longer viable" +- "VCDIFF delta decode failed" +- "Vcdiff delta decode failed with {error}" +- "Delta message decode failure. Previous message id does not equal expected message id" +- "previous id '{id}' is incompatible with message delta {delta}" +- "Failed to decode data: {specific error}" +- "Data is nil" + +## Common Causes + +1. **Delta message sequencing issues** (60% of cases) + - Previous message ID doesn't match expected sequence + - Messages received out of order + - Missing base message for delta decompression + + +2. **Network data corruption** (25% of cases) + - Corrupted delta data during transmission + - Invalid VCDIFF format received + - Network interruption during message transfer + + +3. **Missing dependencies (.NET specific)** (15% of cases) + - IO.Ably.DeltaCodec assembly not found + - Assembly version mismatch + - Strong-naming requirements not met + + +## Resolution Steps + +1. **Allow automatic recovery to complete** + - The SDK automatically reattaches to the channel + - Recovery includes restoring message continuity from the last known point + - No code changes required in most cases + + +2. **Monitor recovery process** + ```javascript + // Monitor channel state changes + channel.on('attaching', (stateChange) => { + if (stateChange.reason?.code === 40018) { + console.log('Delta decode recovery in progress'); + } + }); + + channel.on('attached', () => { + console.log('Channel reattached successfully'); + }); + ``` + + +3. **For .NET users experiencing assembly errors** + - Ensure the IO.Ably.DeltaCodec NuGet package is installed + - Verify assembly versions match the SDK version + - Check that strong-naming requirements are met in your project + + +4. **If errors persist frequently** + - Enable SDK debug logging to capture detailed recovery information + - Check network stability and latency + - Consider temporarily disabling delta compression if the issue continues + + +## Automatic Handling + +Ably SDKs automatically handle this error by: +1. Transitioning the channel to ATTACHING state +2. Reattaching with the previous channel serial +3. Resuming message flow from the correct point +4. No messages are lost during this recovery process + +The recovery is transparent to your application and requires no intervention. + + +## Prevention + +While this error is handled automatically, you can minimize occurrences by: +- Ensuring stable network connectivity +- Keeping SDKs updated to the latest versions +- For .NET applications, ensuring all required assemblies are properly deployed +- Monitoring for patterns that might indicate systematic issues + +## Related Resources + +- [Ably Channels documentation](https://ably.com/docs/channels) +- [Message delta compression](https://ably.com/docs/realtime/channels#delta-compression) +- [Channel state management](https://ably.com/docs/realtime/channels#channel-states) +- [Connection state recovery](https://ably.com/docs/realtime/connection#connection-state-recovery) + +## Need Further Help? + +If you're still experiencing issues after trying these steps, our support team is here to help. + +**Contact Ably Support**: https://ably.com/support + +When contacting support, please provide: +- Your account ID and app ID +- The full error message including error code 40018 +- Steps to reproduce the issue +- Any relevant code snippets (without sensitive credentials) +- The SDK and version you're using + +Our team will help you resolve this issue as quickly as possible. + + + + + + + + + + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/40019-missing-plugin.mdx b/src/pages/docs/platform/errors/codes/40019-missing-plugin.mdx new file mode 100644 index 0000000000..2adf2a66f4 --- /dev/null +++ b/src/pages/docs/platform/errors/codes/40019-missing-plugin.mdx @@ -0,0 +1,231 @@ + + + + + + + + +# Error 40019: Missing Plugin + +## What Happened + +The SDK requires a plugin or module that isn't installed or included in your build. + +## Quick Reference +| Error Code | HTTP Status | Category | Retryable | +|------------|-------------|----------|-----------| +| 40019 | 400 | Client Error (Missing Plugin) | No - requires installing missing plugin | + +## Quick Fix +- Install the missing plugin specified in the error message +- Include the plugin in your SDK initialization +- For modular builds, ensure all required plugins are imported + +## Error Messages + +You may see one of these messages: +- "Missing Vcdiff decoder (https://github.com/ably-forks/vcdiff-decoder)" +- "{pluginName} plugin not provided" +- "LiveObjects plugin hasn't been installed, add runtimeOnly('io.ably:live-objects:') to your dependency tree" +- "missing objects plugin" + +## Common Causes + +1. **VCDiff decoder not installed** (JavaScript/React Native) + - Using delta compression without the VCDiff decoder plugin + - Receiving messages with 'vcdiff' encoding + - Missing TextEncoder polyfill in React Native + + +2. **LiveObjects module missing** (Java/Android) + - Attempting to use LiveObjects features + - Missing runtime dependency in build configuration + + +3. **Experimental plugin not configured** (Go) + - Using experimental objects without plugin configuration + - Missing ExperimentalObjectsPlugin in client options + + +4. **Modular build missing components** (JavaScript) + - Using modular SDK build without required plugins + - Optional features not included in custom build + + +## Resolution Steps + +### JavaScript/TypeScript + +1. **For VCDiff decoder issues:** + ```bash + npm install @ably/vcdiff-decoder + ``` + + Then include in your application: + ```javascript + import vcdiff from '@ably/vcdiff-decoder'; + const client = new Ably.Realtime({ + key: 'your-key', + plugins: { vcdiff } + }); + ``` + + +2. **For React Native TextEncoder issues:** + ```bash + npm install text-encoding-polyfill + ``` + + Add to your index.js: + ```javascript + import 'text-encoding-polyfill'; + ``` + + +3. **For modular build plugins:** + ```javascript + import { Realtime } from 'ably/modular'; + import { + WebSocketTransport, + FetchRequest, + // Include other required plugins + } from 'ably/modular/plugins'; + + const client = new Realtime({ + key: 'your-key', + plugins: { + WebSocketTransport, + FetchRequest, + // Add plugins for features you need + } + }); + ``` + + +### Java/Android + +**For LiveObjects features:** + +Using Gradle: +```gradle +dependencies { + implementation 'io.ably:ably-android:1.x.x' + runtimeOnly 'io.ably:live-objects:1.x.x' // Match SDK version +} +``` + +Using Maven: +```xml + + io.ably + live-objects + 1.x.x + runtime + +``` + + +### Go + +**For Experimental Objects:** +```go +// Implement and configure the experimental objects plugin +opts := &ably.ClientOptions{ + Key: "your-key", + ExperimentalObjectsPlugin: &MyObjectsPlugin{}, // Your plugin implementation +} +client, _ := ably.NewRealtime(opts) +``` + + +## Automatic Handling + +This error requires manual intervention. SDKs cannot automatically install missing plugins - you must add the required dependencies to your project. + +## Prevention + +- **Check documentation** for feature-specific plugin requirements before using advanced features +- **Match versions** - Ensure plugin versions match your SDK version +- **Minimal builds** - Only include plugins for features you actually use to optimize bundle size +- **Test thoroughly** - Verify all required features work in development before deploying + + +## Related Resources +- [Ably SDKs Documentation](https://ably.com/docs/sdks) +- [Delta Compression Guide](https://ably.com/docs/channels#delta-compression) +- [LiveObjects Documentation](https://ably.com/docs/products/liveobjects) +- [Modular JavaScript SDK](https://ably.com/docs/sdks/javascript#modular) + +## Need Further Help? + +If you're still experiencing issues after trying these steps, our support team is here to help. + +**Contact Ably Support**: https://ably.com/support + +When contacting support, please provide: +- Your account ID and app ID +- The full error message including error code 40019 +- Steps to reproduce the issue +- Any relevant code snippets (without sensitive credentials) +- The SDK and version you're using + +Our team will help you resolve this issue as quickly as possible. + + + + + + + + + + + + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/40020-batch-partial-failure.mdx b/src/pages/docs/platform/errors/codes/40020-batch-partial-failure.mdx new file mode 100644 index 0000000000..36178dcf3a --- /dev/null +++ b/src/pages/docs/platform/errors/codes/40020-batch-partial-failure.mdx @@ -0,0 +1,224 @@ + + + + + + + + +# Error 40020: Batch operation partial failure + +## What Happened + +Your batch request completed with partial success—some operations in the batch succeeded while others failed. + +## Quick Reference + +| Error Code | HTTP Status | Category | Retryable | +|------------|-------------|----------|-----------| +| 40020 | 400 | Client Error (Batch Operations) | No - check individual operation errors | + +## Quick Fix + +- Check the `batchResponse` field for individual operation results +- Identify which specific operations failed and their error codes +- Retry only the failed operations with corrected parameters + +## Error Messages + +You may see this message: +- "Batched response includes errors" +- "Batch error" + +The response will always include a `batchResponse` field containing the detailed results for each operation. + +## Common Causes + +1. **Mixed validity in batch operations** (70% of cases) + + - Some channels exist while others don't + - Some tokens are valid while others are expired + - Some messages meet size limits while others exceed them + +2. **Permissions issues for specific operations** (20% of cases) + + - Token has permission for some channels but not others + - Mixed capability requirements across operations + +3. **Resource limits on individual items** (10% of cases) + + - Some messages exceed size limits + - Rate limits hit for specific channels + +## Resolution Steps + +1. **Access the batch response details** + + ```javascript + if (response.error && response.error.code === 40020) { + // Partial success - check individual results + response.batchResponse.forEach((result, index) => { + if (result.error) { + console.log(`Operation ${index} failed:`, result.error.message); + // Handle specific error + } else { + console.log(`Operation ${index} succeeded`); + // Process successful result + } + }); + } + ``` + + +2. **Identify and fix failed operations** + + - Each item in `batchResponse` corresponds to an operation in your original batch + - Failed items contain an `error` object with specific error code and message + - Use the individual error codes to determine the specific fix needed + +3. **Retry only failed operations** + + - Extract failed operations from the batch + - Fix the issues based on individual error messages + - Create a new batch with only the corrected operations + - Submit the retry batch + +## Automatic Handling + + +Ably SDKs recognize error 40020 as a partial success indicator and will not throw exceptions. Instead, they provide access to the `batchResponse` field for you to handle individual results. The SDK will not automatically retry partial failures—you must handle them based on your application logic. + +## Code Examples + +### Handling batch publish partial failures + +```javascript +// Publishing to multiple channels +const batchPublishData = [ + { channel: 'channel1', messages: { data: 'Hello' } }, + { channel: 'channel2', messages: { data: 'World' } }, + { channel: 'restricted-channel', messages: { data: 'Secret' } } +]; + +try { + const response = await ably.request('POST', '/messages', {}, batchPublishData); + console.log('All operations succeeded'); +} catch (err) { + if (err.code === 40020) { + // Handle partial success + const failedOps = []; + err.batchResponse.forEach((result, index) => { + if (result.error) { + console.error(`Channel ${batchPublishData[index].channel} failed:`, result.error.message); + failedOps.push(batchPublishData[index]); + } + }); + + // Optionally retry failed operations after fixing issues + if (failedOps.length > 0) { + console.log('Retrying failed operations...'); + // Fix issues and retry + } + } +} +``` + + +### Batch token revocation with partial failures + +```javascript +// Revoking multiple tokens +const tokensToRevoke = ['token1', 'token2', 'expired-token']; + +const response = await ably.auth.revokeTokens({ tokens: tokensToRevoke }); + +if (response.error?.code === 40020) { + response.batchResponse.forEach((result, index) => { + if (result.error) { + console.log(`Token ${tokensToRevoke[index]} revocation failed:`, result.error.message); + // Token might already be revoked or invalid + } else { + console.log(`Token ${tokensToRevoke[index]} successfully revoked`); + } + }); +} +``` + + +## Affected Endpoints + + +This error can occur with these batch endpoints: +- `POST /messages` - Batch message publishing +- `POST /revokeTokens` - Batch token revocation +- `GET /presence` - Batch presence retrieval + +## Related Resources + +- [Batch Publishing Documentation](https://ably.com/docs/rest/messages#batch-publish) +- [API Reference - Batch Operations](https://ably.com/docs/api/rest-api#batch-operations) +- [Error Handling Best Practices](https://ably.com/docs/best-practice/error-handling) +- Related errors: [40140](./40140-token-error.md) (Token errors), [40171](./40171-channel-error.md) (Channel errors) + +## Need Further Help? + +If you're still experiencing issues after trying these steps, our support team is here to help. + +**Contact Ably Support**: https://ably.com/support + +When contacting support, please provide: +- Your account ID and app ID +- The full error message including error code 40020 +- Steps to reproduce the issue +- Any relevant code snippets (without sensitive credentials) +- The SDK and version you're using + +Our team will help you resolve this issue as quickly as possible. + + + + + + + + + + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/40022-invalid-resource-or-deprecated-feature.mdx b/src/pages/docs/platform/errors/codes/40022-invalid-resource-or-deprecated-feature.mdx new file mode 100644 index 0000000000..5f5f9b3d6f --- /dev/null +++ b/src/pages/docs/platform/errors/codes/40022-invalid-resource-or-deprecated-feature.mdx @@ -0,0 +1,185 @@ + + + + + + + + +# Error 40022: Invalid Resource or Deprecated Feature + +## What Happened + +Your request failed because you're either trying to use a deprecated feature (API Streamer) or your resource validation failed in the Control API. + +## Quick Reference + +| Error Code | HTTP Status | Category | Retryable | +|------------|-------------|----------|-----------| +| 40022 | 400 or 422 | Client Error (Validation/Deprecation) | No - requires configuration fix | + +## Quick Fix + +- If using channels starting with `[product:` - remove these deprecated channel names +- For Control API errors - check the `details` field for specific validation issues +- Contact support@ably.com if migrating from API Streamer + +## Error Messages + +You may see one of these messages: +- "API Streamer is no longer offered, contact support@ably.com for more information" +- "Invalid resource" (with specific details in the response) +- Context-specific validation messages in the `details` field + +## Common Causes + +### 1. **Deprecated API Streamer Usage** (Most common for channel operations) + - Attempting to attach to channels starting with `[product:` + - Using legacy exchange (xchg) channels + - Following outdated documentation referencing API Streamer + + +### 2. **Control API Validation Failures** (For app/rule management) + - **Rule Configuration Issues**: + - Missing or invalid `enveloped` parameter + - Invalid `requestMode` (must be 'single' or 'batch') + - Incompatible enveloped/requestMode combinations + - **Resource Not Found**: + - Invalid queue IDs for AMQP rules + - Non-existent API keys referenced + - **Invalid Parameters**: + - Invalid AWS regions for queues + - Malformed certificates + - Duplicate resource names + + +## Resolution Steps + +### For API Streamer Errors + +1. **Identify deprecated channel names** + - Check if your channel names start with `[product:` + - These channels are no longer supported + + +2. **Update your channel naming** + - Remove the `[product:` prefix + - Use standard Ably channel naming conventions + - See [Channel naming documentation](https://ably.com/docs/channels#name-syntax) + +3. **Contact support for migration assistance** + - Email support@ably.com with your use case + - Include your app ID and current channel patterns + - Support team will help with migration to supported features + + +### For Control API Validation Errors + +1. **Check the error details** + - The response includes a `details` field with specific validation issues + - Example: `"queueId": "Could not find queue with id "` + + +2. **Fix rule configuration issues** + - For enveloped rules: Use `enveloped=true` with `requestMode=batch` + - For non-enveloped rules: Use `enveloped=false` with `requestMode=single` + - Some rule types (CloudFlare, IFTTT, Zapier) don't support enveloped parameter + + +3. **Validate resource parameters** + - For queue regions: Use valid regions (us-east-1-a, eu-west-1-a) + - For resource names: Ensure they're unique within your app + - For certificates: Ensure proper formatting + + +## Automatic Handling + +This error will not be automatically retried by Ably SDKs as it indicates a configuration issue that must be fixed before the operation will succeed. + +## Prevention + +### Avoiding API Streamer Errors +- Never use channel names starting with `[product:` +- Follow current Ably documentation for channel naming +- Remove any references to exchange or xchg channels from your code + +### Avoiding Control API Validation Errors +- Always validate parameters against the [Control API documentation](https://ably.com/docs/api/control-api) +- Use the correct enveloped/requestMode combinations for rules +- Check resource existence before referencing in rules +- Use unique names for all resources + +## Related Resources + +- [Channel naming conventions](https://ably.com/docs/channels#name-syntax) +- [Control API documentation](https://ably.com/docs/api/control-api) +- [Integration rules documentation](https://ably.com/docs/general/integrations) +- Related errors: [40000](./40000-bad-request.mdx), [40400](./40400-not-found.mdx) + +## Need Further Help? + +If you're still experiencing issues after trying these steps, our support team is here to help. + +**Contact Ably Support**: https://ably.com/support + +When contacting support, please provide: +- Your account ID and app ID +- The full error message including error code 40022 +- Steps to reproduce the issue +- Any relevant code snippets (without sensitive credentials) +- The SDK and version you're using + +Our team will help you resolve this issue as quickly as possible. + + + + + + + + + + + + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/40023-protocol-version-required.mdx b/src/pages/docs/platform/errors/codes/40023-protocol-version-required.mdx new file mode 100644 index 0000000000..d90a5f0205 --- /dev/null +++ b/src/pages/docs/platform/errors/codes/40023-protocol-version-required.mdx @@ -0,0 +1,169 @@ + + + + + + + + +# Error 40023: Action requires a newer protocol version + +## What Happened + +Your application tried to use a feature that requires a newer version of the Ably protocol than your current SDK supports. + +## Quick Reference + +| Error Code | HTTP Status | Category | Retryable | +|------------|-------------|----------|-----------| +| 40023 | 400 | Client Error (Protocol Version) | No - requires SDK upgrade | + +## Quick Fix + +- Update your Ably SDK to the latest version +- Ensure your SDK supports protocol version 2 +- After upgrading, the feature will be available immediately + +## Error Messages + +You may see one of these messages: +- "Action requires a newer protocol version" +- "Objects are not supported by your SDK version, please upgrade to an SDK version which uses protocol v2" +- "Message annotations are not supported by your SDK version, please upgrade to an SDK version which uses protocol v2" + +## Common Causes + +1. **Using an outdated SDK version** (90% of cases) + - Your SDK only supports protocol v1 + - Attempting to use LiveObjects or message annotations + - SDK hasn't been updated in several months + +2. **New feature adoption** (10% of cases) + - Trying to implement LiveObjects for collaborative features + - Attempting to use message updates or deletes + - Adding message annotations to existing implementation + +## Resolution Steps + +1. **Check your current SDK version** + - Review your package.json, Gemfile, requirements.txt, or equivalent + - Compare with the latest version on [Ably's download page](https://ably.com/download) + + +2. **Update to the latest SDK version** + + For JavaScript/Node.js: + ```bash + npm install ably@latest + ``` + + For other platforms, see the [SDK installation guide](https://ably.com/docs/getting-started/setup) + + +3. **Verify protocol v2 support** + - Latest SDK versions automatically use protocol v2 + - No additional configuration required + - Features become available immediately after upgrade + + +4. **Test the feature again** + - Your application should now support LiveObjects, message annotations, and other v2 features + - No code changes required beyond the SDK upgrade + +## Automatic Handling + +This is a client configuration error that will not be automatically retried. You must upgrade your SDK version before the operation will succeed. + +## Prevention + +- Keep your Ably SDK updated to the latest stable version +- Subscribe to [Ably's changelog](https://changelog.ably.com) for new feature announcements +- Review SDK requirements when implementing new features +- Use dependency management tools to track SDK updates + +## Features Requiring Protocol v2 + +The following features require protocol version 2: +- **LiveObjects**: Distributed data structures for collaborative features +- **Message annotations**: Metadata attached to messages +- **Message updates**: Editing published messages +- **Message deletes**: Removing published messages + + +## Related Resources + +- [Ably SDK downloads](https://ably.com/download) +- [LiveObjects documentation](https://ably.com/docs/products/liveobjects) +- [Protocol version information](https://ably.com/docs/client-lib-development-guide/protocol-versions) +- Related errors: None specific to protocol versioning + +## Need Further Help? + +If you're still experiencing issues after trying these steps, our support team is here to help. + +**Contact Ably Support**: https://ably.com/support + +When contacting support, please provide: +- Your account ID and app ID +- The full error message including error code 40023 +- Steps to reproduce the issue +- Any relevant code snippets (without sensitive credentials) +- The SDK and version you're using + +Our team will help you resolve this issue as quickly as possible. + + + + + + + + + + + + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/40024-channel-mode-required.mdx b/src/pages/docs/platform/errors/codes/40024-channel-mode-required.mdx new file mode 100644 index 0000000000..fb46c95437 --- /dev/null +++ b/src/pages/docs/platform/errors/codes/40024-channel-mode-required.mdx @@ -0,0 +1,174 @@ + + + + + + + + +# Error 40024: Channel Mode Required for LiveObjects + +## What Happened + +The channel you're trying to use for LiveObjects operations doesn't have the required channel mode configured. + +## Quick Reference + +| Error Code | HTTP Status | Category | Retryable | +|------------|-------------|----------|-----------| +| 40024 | 400 | Client Error (LiveObjects) | No - requires configuration fix | + +## Quick Fix + +- Set the required channel mode (`object_subscribe` or `object_publish`) when creating the channel +- Ensure the channel is configured for LiveObjects before attempting operations +- Check that your channel options include the appropriate mode for your operation + +## Error Messages + +You may see one of these messages: +- "'{mode}' channel mode must be set for this operation" +- "channel mode must be set for this operation" + +The `{mode}` placeholder will be replaced with the specific mode required for your operation. + +## Common Causes + +1. **Missing channel mode configuration** (90% of cases) + - Channel created without LiveObjects mode options + - Default channel configuration used instead of LiveObjects-specific setup + + +2. **Incorrect mode for operation** (10% of cases) + - Using `object_subscribe` mode for publish operations + - Using `object_publish` mode for subscribe operations + + +## Resolution Steps + +1. **Configure the channel with the required mode** + + + For JavaScript/TypeScript: + ```javascript + // For subscribe operations + const channel = ably.channels.get('my-channel', { + modes: ['object_subscribe'] + }); + + // For publish operations + const channel = ably.channels.get('my-channel', { + modes: ['object_publish'] + }); + + // For both operations + const channel = ably.channels.get('my-channel', { + modes: ['object_subscribe', 'object_publish'] + }); + ``` + + + For Java/Kotlin: + ```java + // Configure channel with required modes + ChannelOptions options = new ChannelOptions(); + options.modes = new String[] { "object_subscribe", "object_publish" }; + Channel channel = ably.channels.get("my-channel", options); + ``` + + +2. **Verify your LiveObjects operations match the configured mode** + - Use `object_subscribe` mode for receiving object updates + - Use `object_publish` mode for creating or modifying objects + - Use both modes if your application needs full read/write access + + +3. **Check your channel configuration before operations** + ```javascript + // Verify channel has required modes + const channel = ably.channels.get('my-channel'); + if (!channel.options?.modes?.includes('object_subscribe')) { + // Reconfigure channel with required mode + channel = ably.channels.get('my-channel', { + modes: ['object_subscribe', 'object_publish'] + }); + } + ``` + + +## Automatic Handling + +This is a configuration error that will not be automatically retried. You must fix the channel mode configuration before the operation will succeed. + +## Prevention + +- Always configure channels with appropriate modes when using LiveObjects +- Set both `object_subscribe` and `object_publish` modes if your application performs both read and write operations +- Consider creating a helper function to ensure consistent channel configuration across your application +- Review the [LiveObjects documentation](https://ably.com/docs/liveobjects) for complete configuration requirements + +## Related Resources + +- [LiveObjects documentation](https://ably.com/docs/liveobjects) +- [Channel configuration guide](https://ably.com/docs/channels) +- [LiveObjects API reference](https://ably.com/docs/api/realtime-sdk/channels#channel-options) +- Related errors: [40019](./40019-missing-plugin.md) (missing LiveObjects dependency) + +## Need Further Help? + +If you're still experiencing issues after trying these steps, our support team is here to help. + +**Contact Ably Support**: https://ably.com/support + +When contacting support, please provide: +- Your account ID and app ID +- The full error message including error code 40024 +- Steps to reproduce the issue +- Any relevant code snippets (without sensitive credentials) +- The SDK and version you're using + +Our team will help you resolve this issue as quickly as possible. + + + + + + + + + + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/40030-invalid-publish-request.mdx b/src/pages/docs/platform/errors/codes/40030-invalid-publish-request.mdx new file mode 100644 index 0000000000..4555558c09 --- /dev/null +++ b/src/pages/docs/platform/errors/codes/40030-invalid-publish-request.mdx @@ -0,0 +1,174 @@ + + + + + + + + +# Error 40030: Invalid publish request + +## What Happened + +Your publish request to Ably was malformed and could not be processed. + +## Quick Reference + +| Error Code | HTTP Status | Category | Retryable | +|------------|-------------|----------|-----------| +| 40030 | 400 | Client Error (Publishing) | No - requires fixing the request format | + +## Quick Fix + +- Check if you're sending an `extras` field - it must be a plain object, not a string or array +- Verify your message structure matches the API documentation +- Review the specific error message for details about what's invalid + +## Error Messages + +You'll see one of these messages: +- "Invalid publish request (unspecified)" +- "extras if present must be an object" + +## Common Causes + +1. **Invalid extras field format** (90% of cases) + + - Sending `extras` as a string instead of an object + - Using JSON.stringify on the extras value + - Sending `extras` as a number, boolean, or array + - Form-encoded requests with incorrectly structured extras + +2. **Malformed message structure** (10% of cases) + + - General publish request validation failure + - Invalid parameter combinations + +## Resolution Steps + +1. **If the error mentions "extras must be an object"** + + + Check your publish code - the `extras` field must be a plain JavaScript object: + + ❌ **Wrong: Sending extras as a string** + ```javascript + channel.publish({ + name: 'message', + data: 'Hello', + extras: JSON.stringify({ ref: 'some-ref' }) // This is a string! + }); + ``` + + ✅ **Correct: Sending extras as an object** + ```javascript + channel.publish({ + name: 'message', + data: 'Hello', + extras: { ref: 'some-ref' } // Plain object + }); + ``` + + +2. **For REST API requests with form encoding** + + + When using `Content-Type: application/x-www-form-urlencoded`, structure your data properly. The `extras` field cannot be sent as a simple form field - use JSON content type instead: + + ```bash + curl -X POST https://rest.ably.io/channels/my-channel/messages \ + -H "Content-Type: application/json" \ + -H "Authorization: Basic YOUR_API_KEY" \ + -d '{"name":"event","data":"hello","extras":{"ref":"123"}}' + ``` + +3. **Review your publish request structure** + + + Ensure your message follows the correct format: + - `name`: (optional) Event name as a string + - `data`: Message payload (string, JSON object, or buffer) + - `extras`: (optional) Must be a plain object or omitted entirely + - `id`: (optional) Unique message ID for idempotency + +4. **Check the full error message** + + + Error 40030 often includes specific details beyond the generic message. Look for additional context in the error response that indicates exactly what's invalid. + +## Automatic Handling + +This is a client error that indicates a problem with your request format. Ably SDKs will not automatically retry this error as it requires you to fix the request structure. + +## Prevention + +- Always pass `extras` as a plain JavaScript object, never as a stringified JSON +- Omit the `extras` field entirely if you don't need it +- Use JSON content type for REST API requests when sending complex objects +- Validate message structure before publishing in production code + +## Related Resources + +- [Publishing messages documentation](https://ably.com/docs/channels#publish) +- [Message structure reference](https://ably.com/docs/api/rest-sdk#message) +- Related errors: [40009](https://ably.com/docs/platform/errors/codes/40009) (message too large), [40032](https://ably.com/docs/platform/errors/codes/40032) (impermissible extras field) + +## Need Further Help? + +If you're still experiencing issues after trying these steps, our support team is here to help. + +**Contact Ably Support**: https://ably.com/support + +When contacting support, please provide: +- Your account ID and app ID +- The full error message including error code 40030 +- Steps to reproduce the issue +- Any relevant code snippets (without sensitive credentials) +- The SDK and version you're using + +Our team will help you resolve this issue as quickly as possible. + + + + + + + + + + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/40031-invalid-message-id.mdx b/src/pages/docs/platform/errors/codes/40031-invalid-message-id.mdx new file mode 100644 index 0000000000..bd77845dc8 --- /dev/null +++ b/src/pages/docs/platform/errors/codes/40031-invalid-message-id.mdx @@ -0,0 +1,202 @@ + + + + + + + + +# Error 40031: Invalid message ID + +## What Happened + +The message ID you specified doesn't meet the requirements for idempotent message publishing. + +## Quick Reference + +| Error Code | HTTP Status | Category | Retryable | +|------------|-------------|----------|-----------| +| 40031 | 400 | Client Error (Publishing) | No - requires fixing message ID format | + +## Quick Fix + +- Remove custom message IDs to let Ably generate them automatically +- Or ensure all messages in a batch have string IDs (not just some) +- For multi-message publishes, use the format: `baseMsgId:0`, `baseMsgId:1`, etc. + +## Error Messages + +You may see one of these messages: +- "Client-specified message id missing or not a string in some messages of a multi-message ProtocolMessage" +- "Client-specified message ids do not match the required format for multi-message ProtocolMessages" +- "Invalid publish request (invalid client-specified id)" +- "Invalid request: client-specified message id does not contain fragment part" + +## Common Causes + +1. **Mixed ID specification** (60% of cases) + - Some messages in a batch have IDs while others don't + - All messages must have IDs or none should have IDs + + +2. **Incorrect multi-message format** (30% of cases) + - When publishing multiple messages with IDs, they must follow: `baseMsgId:0`, `baseMsgId:1`, etc. + - Sequential indexing starting at 0 is required + + +3. **Invalid ID type** (10% of cases) + - Message IDs must be strings + - Numbers or other types are not accepted + + +## Resolution Steps + +1. **For single message publishing: Use any string ID or remove ID** + ```javascript + // ✅ Correct: Let Ably generate the ID + channel.publish('event', data); + + // ✅ Correct: Custom string ID for idempotency + channel.publish({ name: 'event', data: payload, id: 'unique-msg-123' }); + + // ❌ Wrong: Non-string ID + channel.publish({ name: 'event', data: payload, id: 12345 }); + ``` + + +2. **For multi-message publishing: Follow the required format** + ```javascript + // ❌ Wrong: Mixed ID specification + channel.publish([ + { name: 'event1', data: 'data1', id: 'msg1' }, + { name: 'event2', data: 'data2' } // Missing ID! + ]); + + // ❌ Wrong: Incorrect format for multiple messages + channel.publish([ + { name: 'event1', data: 'data1', id: 'msg1' }, + { name: 'event2', data: 'data2', id: 'msg2' } + ]); + + // ✅ Correct: Proper format with base ID and sequential indices + channel.publish([ + { name: 'event1', data: 'data1', id: 'batch123:0' }, + { name: 'event2', data: 'data2', id: 'batch123:1' } + ]); + + // ✅ Correct: No IDs specified (Ably generates them) + channel.publish([ + { name: 'event1', data: 'data1' }, + { name: 'event2', data: 'data2' } + ]); + ``` + + +3. **Verify your implementation** + - Check that all IDs are strings + - Ensure consistent ID usage across all messages + - For batches, verify the sequential index pattern + + +## Automatic Handling + +This is a client error that will not be automatically retried. You must fix the message ID format before the publish operation will succeed. + +## Code Examples + +### Idempotent Publishing with Custom IDs + +```javascript +// Single message with custom ID for idempotency +const messageId = `order-${orderId}-${timestamp}`; +await channel.publish({ + name: 'order.created', + data: orderData, + id: messageId // Prevents duplicate processing +}); + +// Atomic batch publish with proper ID format +const batchId = `batch-${Date.now()}`; +const messages = orders.map((order, index) => ({ + name: 'order.created', + data: order, + id: `${batchId}:${index}` // Required format for batches +})); +await channel.publish(messages); +``` + + +## Prevention + +- Use Ably's automatic ID generation unless you specifically need idempotent publishing +- When using custom IDs, always use strings +- For batch operations, either specify IDs for all messages or none +- Follow the `baseMsgId:index` pattern for multi-message publishes +- Test your ID generation logic to ensure compliance + +## Related Resources + +- [Idempotent message publishing](https://ably.com/docs/realtime/messages#idempotency) +- [Message batching](https://ably.com/docs/rest/messages#batch) +- [Publishing messages](https://ably.com/docs/realtime/messages#publish) + +## Need Further Help? + +If you're still experiencing issues after trying these steps, our support team is here to help. + +**Contact Ably Support**: https://ably.com/support + +When contacting support, please provide: +- Your account ID and app ID +- The full error message including error code 40031 +- Steps to reproduce the issue +- Any relevant code snippets (without sensitive credentials) +- The SDK and version you're using + +Our team will help you resolve this issue as quickly as possible. + + + + + + + + + + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/40032-invalid-extras-field.mdx b/src/pages/docs/platform/errors/codes/40032-invalid-extras-field.mdx new file mode 100644 index 0000000000..088b8e4bb9 --- /dev/null +++ b/src/pages/docs/platform/errors/codes/40032-invalid-extras-field.mdx @@ -0,0 +1,209 @@ + + + + + + + + +# Error 40032: Invalid extras field + +## What Happened + +Your message contains fields in the `extras` object that are not allowed by Ably, or the allowed fields have incorrect values. + +## Quick Reference + +| Error Code | HTTP Status | Category | Retryable | +|------------|-------------|----------|-----------| +| 40032 | 400 | Client Error (Message Validation) | No - requires fixing the message structure | + +## Quick Fix + +- Move custom data into `extras.headers` as flat key-value pairs +- Remove `ephemeral` flag from presence or state messages +- Ensure header values are only string, number, boolean, or null + +## Error Messages + +You may see one of these messages: +- "Invalid publish request (impermissible extras field)" +- "Presence cannot be ephemeral" +- "State messages cannot be ephemeral" +- "extras.headers if present must be a map" +- "malformed extras.headers value; acceptable types are string|number|boolean|null" +- "extras.ephemeral if present must be a boolean" +- "Message has impermissible extras fields: [field names]" + +## Common Causes + +1. **Adding custom fields directly to extras** (60% of cases) + - Putting arbitrary data in the extras object + - Using fields that are reserved for Ably functionality + + +2. **Incorrect headers structure** (25% of cases) + - Using nested objects or arrays in headers + - Using non-primitive types as header values + + +3. **Ephemeral flag on wrong message types** (15% of cases) + - Setting `ephemeral: true` on presence messages + - Setting `ephemeral: true` on state messages + + +## Resolution Steps + +1. **Review your extras field structure** + - The `extras` field is reserved for Ably-specific functionality + - Only certain fields are allowed in extras + + +2. **Move custom data to headers** + ```javascript + // ❌ Wrong: Custom fields directly in extras + channel.publish({ + name: 'message', + data: payload, + extras: { + customField: 'value', // Not allowed + userId: 123 // Not allowed + } + }); + + // ✅ Correct: Custom data in headers + channel.publish({ + name: 'message', + data: payload, + extras: { + headers: { + customField: 'value', // Allowed + userId: 123 // Allowed + } + } + }); + ``` + + +3. **Ensure headers are flat key-value pairs** + ```javascript + // ❌ Wrong: Nested objects in headers + extras: { + headers: { + user: { id: 123, name: 'John' } // Not allowed - nested object + } + } + + // ✅ Correct: Flat structure with primitive values + extras: { + headers: { + userId: 123, // string, number, boolean, or null only + userName: 'John', + isActive: true, + metadata: null + } + } + ``` + + +4. **Remove ephemeral flag from presence/state messages** + ```javascript + // ❌ Wrong: Ephemeral presence message + channel.presence.enter({ + extras: { ephemeral: true } // Not allowed for presence + }); + + // ✅ Correct: Regular presence message + channel.presence.enter({ + // No ephemeral flag for presence messages + }); + ``` + + +5. **For Integrations: Use ASCII header names** + - When using Integrations (formerly Reactor), ensure header names use only ASCII characters + - Headers will be converted to HTTP, AMQP, or other protocol headers + + +## Automatic Handling + +This is a client error that will not be automatically retried. You must fix the message structure before the operation will succeed. + +## Prevention + +- **Structure validation**: Always validate your extras field structure before publishing +- **Use headers for custom data**: Place all application-specific data in `extras.headers` +- **Keep headers flat**: Ensure headers contain only primitive values (string, number, boolean, null) +- **Message type awareness**: Remember that presence and state messages cannot be ephemeral +- **ASCII header names**: Use only ASCII characters in header names when using Integrations + + +## Related Resources + +- [Message extras documentation](https://ably.com/docs/api/realtime-sdk/messages#extras) +- [Publishing messages](https://ably.com/docs/channels#publish) +- [Presence documentation](https://ably.com/docs/presence) +- Related errors: [40000](./40000-bad-request.md) (General bad request) + +## Need Further Help? + +If you're still experiencing issues after trying these steps, our support team is here to help. + +**Contact Ably Support**: https://ably.com/support + +When contacting support, please provide: +- Your account ID and app ID +- The full error message including error code 40032 +- Steps to reproduce the issue +- Any relevant code snippets (without sensitive credentials) +- The SDK and version you're using + +Our team will help you resolve this issue as quickly as possible. + + + + + + + + + + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/40099-internal-testing-error.mdx b/src/pages/docs/platform/errors/codes/40099-internal-testing-error.mdx new file mode 100644 index 0000000000..2a4579852e --- /dev/null +++ b/src/pages/docs/platform/errors/codes/40099-internal-testing-error.mdx @@ -0,0 +1,131 @@ + + + + + + + + +# Error 40099: Internal Testing Error + +## What Happened + +The system encountered an internal testing or development error that should not occur during normal operations. + +## Quick Reference + +| Error Code | HTTP Status | Category | Retryable | +|------------|-------------|----------|-----------| +| 40099 | 400 | Client Error (Testing/Development) | No - indicates configuration or testing issue | + +## Quick Fix + +- Remove any `_forceNack` parameters from your requests +- Check if you're using undocumented testing parameters +- Review your message metadata structure if using advanced features + +## Error Messages + +You may see one of these messages: +- "Message rejected by request" +- "Unable to add userClaim to message" + +## Common Causes + +1. **Testing parameter in production** (Most common) + - Using `_forceNack=true` parameter in requests + - This is an internal testing parameter not intended for production use + + +2. **Message metadata processing failure** (Rare) + - Internal failure when adding user claims to message extras + - Related to advanced message features + + +## Resolution Steps + +1. **Check for testing parameters** + - Review your publish requests for any `_forceNack` parameter + - Remove this parameter as it's intended for internal testing only + + +2. **Review message structure** + - If you're using advanced message features, verify your message structure + - Ensure message extras and metadata are properly formatted + + +3. **For SDK testing** + - If you're intentionally testing error handling, this error is expected + - The `_forceNack` parameter deliberately triggers this error for testing purposes + + +## Automatic Handling + +This error is not automatically retried by Ably SDKs as it indicates either: +- Intentional testing behavior +- A structural issue with the request that requires correction + +## Related Resources + +- [Ably Pub/Sub Documentation](https://ably.com/docs/pubsub) +- [Message Structure Documentation](https://ably.com/docs/channels/messages) + +## Need Further Help? + +This error code has limited documentation as it's primarily used for internal testing. If you encounter this error during normal operations, please contact Ably support at https://ably.com/support with: +- Your account ID and app ID +- The full error message including error code 40099 +- The exact request that triggered the error +- Any parameters you're using in your publish requests + +Our support team will help you resolve this issue as quickly as possible. + + + + + + + + + + + + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/40100-unauthorized-access.mdx b/src/pages/docs/platform/errors/codes/40100-unauthorized-access.mdx new file mode 100644 index 0000000000..e258bc906e --- /dev/null +++ b/src/pages/docs/platform/errors/codes/40100-unauthorized-access.mdx @@ -0,0 +1,187 @@ + + + + + + + + +# Error 40100: Unauthorized access + +## What Happened + +An action cannot be performed due to a lack of authorization. This is distinct from invalid credentials (40101) or other authentication errors. + +## Quick Reference + +| Error Code | HTTP Status | Category | Retryable | +|------------|-------------|----------|-----------| +| 40100 | 401 | Authentication | No - requires fixing authorization | + +## Quick Fix + +- Verify your API key has the necessary capabilities for the operation +- Check device credentials match the expected values for push operations +- Ensure you're not attempting to modify immutable properties + +## Error Messages + +You may see one of these messages: +- "Access refused" +- "Unauthorized" +- "Token deviceId does not match requested device operation" +- "cannot update device id or appId" +- "cannot update transportType" +- "Incompatible deviceSecret specified for device access" +- "Incompatible updateToken specified for device access" +- "Unable to authenticate device credentials; device not found" +- "push not enabled for this channel" +- "Invalid API key. Ensure you have a valid key configured." +- "Failed to get a token" + +## Common Causes + +1. **Device token mismatches** (60% of cases) + - Token deviceId doesn't match the requested device operation + - Environment switching (staging to production) with existing device credentials + - Device credentials persisting across environment changes + + +2. **Attempting to modify immutable properties** (20% of cases) + - Trying to update device ID or app ID + - Non-admin users attempting to update transport type + - These properties cannot be changed after creation + + +3. **Device authentication failures** (15% of cases) + - Incompatible deviceSecret or updateToken + - Device not found in the system + - Credential validation failures + + +4. **Push notification issues** (5% of cases) + - Push not enabled for the requested channel + - Insufficient permissions for push operations + + +## Resolution Steps + +1. **For device token mismatches** + - Always deactivate push notifications before switching environments + + - If deactivation fails with 40100, consider device reset + - Ensure device credentials are properly cleared when switching between staging and production + - Implement a device re-registration flow when encountering this error + + +2. **For immutable property errors** + - Device ID and app ID cannot be updated after creation + - Create a new device registration instead of updating these fields + - Transport type updates require admin privileges + + +3. **For device authentication issues** + - Verify the deviceSecret or updateToken matches the stored values + - Check that the device exists in your Ably app + - Ensure you're using credentials from the correct environment + + +4. **For push notification problems** + - Verify push is enabled for the channel in your app settings + - Check your API key has the necessary push capabilities + - Review the [push notifications documentation](https://ably.com/docs/push) + + +5. **For API key issues** + - Verify your API key is valid and not revoked + - Check the key has the necessary capabilities for your operation + - For CLI users, run `ably login` to re-authenticate + + +## Automatic Handling + +This is an authorization error that will not be automatically retried. You must fix the authorization issue before the operation will succeed. SDKs may suggest re-authentication or provide specific error recovery mechanisms. + + +## Prevention + +- Store device registration state locally to track environment +- Implement device deactivation before environment switches +- Validate deviceId consistency across token lifecycle +- Ensure token claims match device operations +- Implement proper token refresh mechanisms + + +## Related Resources + +- [Authentication documentation](https://ably.com/docs/auth) +- [Push notifications guide](https://ably.com/docs/push) +- [Device registration](https://ably.com/docs/push/activate) +- Related errors: [40101](https://help.ably.io/error/40101), [40102](https://help.ably.io/error/40102), [40103](https://help.ably.io/error/40103) + +## Need Further Help? + +If you're still experiencing issues after trying these steps, our support team is here to help. + +**Contact Ably Support**: https://ably.com/support + +When contacting support, please provide: +- Your account ID and app ID +- The full error message including error code 40100 +- Steps to reproduce the issue +- Any relevant code snippets (without sensitive credentials) +- The SDK and version you're using + +Our team will help you resolve this issue as quickly as possible. + + + + + + + + + + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/40101-invalid-credentials.mdx b/src/pages/docs/platform/errors/codes/40101-invalid-credentials.mdx index 5ebf5b3c8a..06b32e1355 100644 --- a/src/pages/docs/platform/errors/codes/40101-invalid-credentials.mdx +++ b/src/pages/docs/platform/errors/codes/40101-invalid-credentials.mdx @@ -1,20 +1,20 @@ - + - + # Error 40101: Invalid credentials ## What Happened -Your authentication credentials are invalid or incorrectly formatted, preventing access to Ably services. +Your authentication credentials are invalid, incorrectly formatted, or cannot be verified by Ably's authentication system. ## Quick Reference @@ -24,9 +24,10 @@ Your authentication credentials are invalid or incorrectly formatted, preventing ## Quick Fix -- Verify your API key is complete and correctly formatted: `[AppId].[keyId]:[keySecret]` -- Check for typos or missing characters in your API key -- Ensure clientId matches between token generation and client initialization +- Verify your API key is complete with all three parts: `[AppId].[keyId]:[keySecret]` +- Remove any leading or trailing spaces from your API key +- For token auth, ensure the token hasn't been modified after generation +- Check that clientId matches between token and client initialization ## Error Messages @@ -39,6 +40,7 @@ You may see one of these messages: - "Invalid clientId for credentials" - "Unable to set different clientId from that given in options" - "Unable to handle request no application id found in request" +- "No key specified: no means to generate a token" ## Common Causes @@ -48,36 +50,48 @@ You may see one of these messages: - Key doesn't follow format: `[AppId].[keyId]:[keySecret]` - Empty or whitespace-only key string - Copy-paste errors with leading/trailing spaces + - Incomplete key from environment variables -2. **Token MAC verification failures** (20% of cases) - - - Altered token request JSON after signature generation - - Incorrect key used for token generation +2. **Token MAC verification failures** (15% of cases) + + - Token request JSON modified after MAC generation + - Incorrect key used for token generation vs verification - Token tampering or corruption during transmission + - Legacy token format validation failures 3. **ClientId mismatches** (10% of cases) - Different clientId between token and client constructor - Attempting to change clientId on existing connection - Empty or wildcard clientId when binding is required + - JWT missing x-ably-clientId header + +4. **Browser or network issues** (5% of cases) + + - Browser extensions stripping Authorization headers (Chrome/Edge) + - Corporate proxies removing authentication + - Network timeouts during authentication + - Frontdoor vs frontend routing inconsistencies ## Resolution Steps 1. **Verify your API key format** - + - Log into your [Ably dashboard](https://ably.com/dashboard) - Navigate to your app → "API Keys" tab - Copy the complete key including all three parts: - App ID (e.g., `xVLyHw`) - Key ID (e.g., `rPSJgQ`) - Key Secret (e.g., `U6RN3LJvZzV3DXJk`) - - Full format: `xVLyHw.rPSJgQ:U6RN3LJvZzV3DXJk` + - Full format example: `xVLyHw.rPSJgQ:U6RN3LJvZzV3DXJk` + - Ensure no spaces before or after the key 2. **Check your implementation** - - Remove any leading or trailing whitespace from the key + - Verify environment variables are loading correctly - Ensure the key contains exactly one period (.) and one colon (:) - - Verify environment variables are loading correctly if used + - Check that your key isn't being truncated or modified + - Enable debug logging to see the actual key being used 3. **For token authentication issues** @@ -85,12 +99,23 @@ You may see one of these messages: - Verify the same API key is used for both token generation and verification - Check that clientId in token matches clientId in client options - For JWT, confirm clientId is set in the x-ably-clientId header + - Generate a fresh token to rule out expiration issues 4. **Debug authentication problems** - + - Enable debug logging in your SDK to see detailed authentication flow - - Check for browser extensions or proxies that might strip Authorization headers + - Check for browser extensions that might strip Authorization headers (Chrome/Edge) + - Test with a different browser or incognito mode + - Verify corporate proxies aren't interfering with authentication - Test with a fresh API key to rule out key-specific issues + - Try forcing backend routing with `_forceHandleBy=frontend` parameter if intermittent + +5. **For clientId issues** + + - Ensure clientId is consistent across token generation and client initialization + - Don't attempt to change clientId on an existing connection + - Avoid using empty strings or wildcards ('*') for clientId when binding + - Review [Client ID documentation](https://ably.com/docs/auth/identified-clients) ## Automatic Handling @@ -112,10 +137,13 @@ const ably = new Ably.Realtime('xVLyHw.rPSJgQ'); // ❌ Wrong: Incomplete key with typo const ably = new Ably.Realtime('xVLyHw.rPSJ:U6RN3LJvZzV3DXJk'); + +// ✅ Correct: From environment variable (ensure it's loaded) +const ably = new Ably.Realtime(process.env.ABLY_API_KEY); ``` ### ClientId Configuration - + ```javascript // ✅ Correct: Consistent clientId const tokenParams = { clientId: 'user123' }; @@ -131,14 +159,59 @@ const client = new Ably.Realtime({ token: token, clientId: 'differentUser' // Will cause 40101 error }); + +// ❌ Wrong: Empty or wildcard clientId when binding +const client = new Ably.Realtime({ + token: token, + clientId: '' // Cannot be empty when binding +}); ``` +### Token Request Validation + +```javascript +// ✅ Correct: Valid token request structure +const tokenRequest = { + keyName: "I2E_JQ.r_aOYg", + clientId: "foo", + ttl: 43200000, + timestamp: Date.now(), + capability: JSON.stringify({"*":["*"]}), + nonce: generateNonce(), + mac: generateMac() // Must be generated AFTER all other fields are set +}; + +// ❌ Wrong: Modifying after MAC generation +tokenRequest.mac = generateMac(); +tokenRequest.clientId = "bar"; // This invalidates the MAC +``` + +## Prevention + +- Store API keys securely in environment variables, not in code +- Implement proper error handling for authentication failures +- Use token authentication for client-side applications +- Test authentication in development before deploying +- Monitor authentication error rates to detect issues early +- Use debug logging during development to catch authentication problems + +## Performance Impact + +Authentication failures prevent all Ably operations: +- No messages can be published +- No channels can be subscribed +- Presence operations will fail +- Connection cannot be established + +The error does not trigger automatic retries, preventing unnecessary load on the authentication system. + ## Related Resources - [Authentication documentation](https://ably.com/docs/auth) - [API key best practices](https://ably.com/docs/auth/basic) - [Token authentication guide](https://ably.com/docs/auth/token) - [Client ID explained](https://ably.com/docs/auth/identified-clients) +- [Debug logging guide](https://ably.com/docs/realtime/connection#connection-state-recovery) - Related errors: [40102 - Token expired](https://help.ably.io/error/40102), [40400 - Not found](https://help.ably.io/error/40400) ## Need Further Help? @@ -153,6 +226,8 @@ When contacting support, please provide: - Steps to reproduce the issue - Any relevant code snippets (without sensitive credentials) - The SDK and version you're using +- Whether the error is intermittent or consistent +- Browser and version (for web applications) Our team will help you resolve this issue as quickly as possible. @@ -164,6 +239,7 @@ Our team will help you resolve this issue as quickly as possible. - Analysis File: https://github.com/ably/ably-os/blob/main/output/error-codes/research/40101-analysis.md - Knowledge File: https://github.com/ably/ably-os/blob/main/output/error-codes/research/40101-knowledge.md - Editorial Notes: https://github.com/ably/ably-os/blob/main/src/prompts/errors/editorial-notes.md (lines 69-72 for 40101 - no specific notes) +- Existing Documentation: https://github.com/ably/docs/blob/main/src/pages/docs/platform/errors/codes/40101-invalid-credentials.mdx (enhanced based on new research) - Error Code Documentation Writing Guide: https://github.com/ably/ably-os/blob/main/src/prompts/shared-resources/error-code-doc-writing-guide.md - Ably Style Guide: https://github.com/ably/ably-os/blob/main/src/prompts/shared-resources/ably-style-guide.md --> @@ -173,40 +249,59 @@ Our team will help you resolve this issue as quickly as possible. - Token MAC verification guidance from https://github.com/ably/ably-os/blob/main/output/error-codes/research/40101-knowledge.md lines 18-35 - ClientId mismatch resolution from https://github.com/ably/ably-os/blob/main/output/error-codes/research/40101-knowledge.md lines 37-42 - Debug logging recommendation from https://github.com/ably/ably-os/blob/main/output/error-codes/research/40101-knowledge.md lines 43-49 + - Browser extension issues from https://github.com/ably/ably-os/blob/main/output/error-codes/research/40101-knowledge.md lines 273-280 +- Content Added: + - Browser-specific issues (Chrome/Edge extensions) from knowledge file + - Environment variable loading issues from analysis + - Frontdoor vs frontend routing workaround from knowledge file + - Prevention section for proactive error avoidance + - Performance impact section - Content Excluded: - Internal Slack discussion URLs (not appropriate for customer documentation) - Specific customer names from support tickets - - Technical implementation details about frontdoor/frontend routing + - Technical implementation details about internal routing + - HTTP status inconsistency details (403 vs 401) to avoid confusion - Recommendations Source: - Resolution steps based on code analysis patterns and FAQ content - No exponential backoff recommended per editorial notes + - Browser troubleshooting from support patterns - Code Examples Rationale: - - Included API key format examples as this is the primary cause of the error (70% of cases) - - Included clientId configuration as it's a common confusion point - - Examples verified against SDK patterns in analysis file + - API key format examples essential (70% of cases per analysis) + - ClientId configuration critical for token auth issues + - Token request validation shows MAC generation timing + - Environment variable example added based on common issues + - All examples verified against SDK patterns in analysis file --> + + + + + + + +# Error 40102: Incompatible credentials + +## What Happened + +Your authentication credentials contain mismatched or incompatible information that prevents a successful connection. + +## Quick Reference + +| Error Code | HTTP Status | Category | Retryable | +|------------|-------------|----------|-----------| +| 40102 | 401/403/400 | Client Error (Authentication) | No - requires fixing credentials | + +## Quick Fix + +- Ensure your client ID remains consistent across tokens and connections +- Use the same API key throughout your authentication flow +- For user login scenarios, disconnect and reconnect with new credentials + +## Error Messages + +You may see one of these messages: +- "Invalid clientId for credentials" +- "Mismatch between clientId in token ({token.clientId}) and current clientId ({this.clientId})" +- "Unable to update auth options with incompatible key" +- "Incompatible keys specified" +- "Client ID is immutable once configured for a client. Client ID cannot be changed to '{new_client_id}'" +- "Unexpected clientId mismatch: client has {current}, requested {requested}" + +## Common Causes + +1. **Client ID mismatch during user login** (60% of cases) + - User transitions from anonymous to authenticated state + - JWT token contains different client ID than current connection + - User switches accounts while maintaining same connection + + +2. **Different API keys in authentication flow** (20% of cases) + - Attempting to authorize with different API key than originally configured + - Mixing API keys between token generation and client initialization + + +3. **Attempting to change immutable client ID** (15% of cases) + - Trying to update client ID after it's been set + - Client ID cannot be changed once configured (unless original was wildcard '*') + + +4. **Token client ID conflicts** (5% of cases) + - Token contains client ID that doesn't match configured client ID + - Using wildcard '*' client ID inappropriately with credentials + + +## Resolution Steps + +1. **Verify client ID consistency** + - Check that all tokens use the same client ID + - Ensure your authentication callback returns consistent client IDs + - Review token generation to confirm correct client ID assignment + + +2. **For user authentication transitions** + - Disconnect the current connection when user logs in/out + - Create a new connection with updated credentials + - Reattach to channels after reconnecting + + +3. **Check API key usage** + - Use a single API key throughout your application + - Don't mix different API keys in authorize() calls + - Verify key consistency between server and client components + + +4. **Handle client ID immutability** + - Never attempt to change client ID after initialization + - If client ID must change, create a new connection + - Use wildcard '*' client ID only when appropriate for your use case + + +5. **Validate token contents** + ```javascript + // Check token details before use + const tokenDetails = await ably.auth.requestToken(); + console.log('Token clientId:', tokenDetails.clientId); + console.log('Current clientId:', ably.auth.clientId); + ``` + + +## Automatic Handling + +This is a client error that will not be automatically retried by Ably SDKs. You must fix the credential mismatch before the operation will succeed. + +**Note**: Laravel Echo implements automatic recovery for this error by detecting client ID mismatches and reconnecting with correct credentials. + + +## Code Examples + +### Correct: Consistent client ID usage +```javascript +const client = new Ably.Realtime({ + authCallback: (tokenParams, callback) => { + // Ensure consistent client ID + tokenParams.clientId = 'user-123'; + fetchToken(tokenParams, callback); + } +}); +``` + + +### Incorrect: Mixing different API keys +```javascript +// ❌ Wrong: Using different API key in authorize +auth.authorize({ + key: 'different-key' // This will trigger 40102 +}); + +// ✅ Correct: Use same key or token-based auth +auth.authorize(); // Uses original configuration +``` + + +### Handle user login transitions +```javascript +// When user logs in with new credentials +async function handleUserLogin(newUserId) { + // 1. Close existing connection + ably.close(); + + // 2. Create new connection with updated auth + const newClient = new Ably.Realtime({ + authCallback: (tokenParams, callback) => { + tokenParams.clientId = newUserId; + fetchTokenForUser(newUserId, callback); + } + }); + + // 3. Reattach to channels + const channel = newClient.channels.get('updates'); + await channel.attach(); +} +``` + + +## Prevention + +- Design your authentication flow with consistent client IDs from the start +- Implement proper user transition handling for login/logout scenarios +- Use a single API key per environment (development, staging, production) +- Test authentication flows thoroughly, including user state transitions +- Consider using token authentication instead of basic auth for better flexibility + + +## Related Resources + +- [Authentication documentation](https://ably.com/docs/auth) +- [Client ID explained](https://ably.com/docs/auth/identified-clients) +- [Token authentication](https://ably.com/docs/auth/token) +- [Connection states](https://ably.com/docs/realtime/connection#connection-states) +- Related errors: [40101](./40101-invalid-api-key.md), [40103](./40103-invalid-use-of-basic-auth.md) + +## Need Further Help? + +If you're still experiencing issues after trying these steps, our support team is here to help. + +**Contact Ably Support**: https://ably.com/support + +When contacting support, please provide: +- Your account ID and app ID +- The full error message including error code 40102 +- Steps to reproduce the issue +- Any relevant code snippets (without sensitive credentials) +- The SDK and version you're using + +Our team will help you resolve this issue as quickly as possible. + + + + + + + + + + + + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/40103-basic-auth-requires-tls.mdx b/src/pages/docs/platform/errors/codes/40103-basic-auth-requires-tls.mdx new file mode 100644 index 0000000000..91d80b90ad --- /dev/null +++ b/src/pages/docs/platform/errors/codes/40103-basic-auth-requires-tls.mdx @@ -0,0 +1,170 @@ + + + + + + + + +# Error 40103: Basic authentication requires TLS + +## What Happened + +Your API key cannot be used over an unencrypted connection for security reasons. + +## Quick Reference + +| Error Code | HTTP Status | Category | Retryable | +|------------|-------------|----------|-----------| +| 40103 | 401 | Client Error (Authentication) | No - requires enabling TLS or switching authentication method | + +## Quick Fix + +- Enable TLS in your client configuration (`tls: true`) +- Use HTTPS/WSS instead of HTTP/WS endpoints +- Or switch to token authentication if TLS cannot be enabled + +## Error Messages + +You may see one of these messages: +- "Invalid use of Basic auth over non-TLS transport" +- "Cannot use Basic Auth over non-TLS connections" +- "Trying to use basic key auth over insecure connection" +- "No authentication parameters supplied" (PHP only) + +## Common Causes + +1. **TLS disabled in configuration** (80% of cases) + + - Setting `tls: false` in client options + - Using HTTP instead of HTTPS endpoints + - Development environments with insecure defaults + +2. **Network restrictions** (15% of cases) + + - Corporate firewall blocking HTTPS/WSS + - Proxy configurations forcing HTTP + - Local development without HTTPS setup + +3. **Missing authentication** (5% of cases - PHP only) + + - No API key, token, authUrl, or authCallback provided + - Empty or null authentication parameters + +## Resolution Steps + +1. **Enable TLS in your configuration** + + - For JavaScript: Set `tls: true` in client options + - For Python: Ensure using HTTPS scheme in connection + - For Ruby: Enable TLS in client configuration + - For Go: Remove `NoTLS` option or set to false + - For PHP: Set `tls` option to true + +2. **Verify your endpoints** + + - Use `https://rest.ably.io` not `http://rest.ably.io` + - Use `wss://realtime.ably.io` not `ws://realtime.ably.io` + - Default endpoints already use TLS + +3. **Alternative: Use token authentication** + + - Token authentication can work over non-TLS connections + - Generate tokens on your secure server + - Configure client with `authUrl` or `authCallback` + - See [Token Authentication documentation](https://ably.com/docs/auth/token) + +4. **For development environments** + + - Use the sandbox environment which supports TLS + - Set up local HTTPS with self-signed certificates + - Or switch to token authentication for local testing + +## Automatic Handling + +This is a security policy error that will not be automatically retried. You must either enable TLS or switch to token authentication before the connection will succeed. + +## Prevention + +- Always use TLS in production environments +- Default to `tls: true` in all configurations +- Use token authentication for client-side applications +- Never transmit API keys over unencrypted connections +- Configure development environments with HTTPS when possible + +## Need Further Help? + +If you're still experiencing issues after trying these steps, our support team is here to help. + +**Contact Ably Support**: https://ably.com/support + +When contacting support, please provide: +- Your account ID and app ID +- The full error message including error code 40103 +- Steps to reproduce the issue +- Any relevant code snippets (without sensitive credentials) +- The SDK and version you're using + +Our team will help you resolve this issue as quickly as possible. + +## Related Resources + +- [Authentication documentation](https://ably.com/docs/auth) +- [Basic authentication guide](https://ably.com/docs/auth/basic) +- [Token authentication guide](https://ably.com/docs/auth/token) +- [TLS/SSL encryption](https://ably.com/docs/security) +- Related errors: [40101](./40101-invalid-api-key.mdx), [40102](./40102-token-expired.mdx) + + + + + + + + + + + + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/40104-timestamp-not-current.mdx b/src/pages/docs/platform/errors/codes/40104-timestamp-not-current.mdx new file mode 100644 index 0000000000..8bef7c0d8c --- /dev/null +++ b/src/pages/docs/platform/errors/codes/40104-timestamp-not-current.mdx @@ -0,0 +1,203 @@ + + + + + + + + +# Error 40104: Timestamp not current + +## What Happened + +The timestamp in your authentication request is too far from Ably's current server time, preventing authentication to protect against replay attacks. + +## Quick Reference + +| Error Code | HTTP Status | Category | Retryable | +|------------|-------------|----------|-----------| +| 40104 | 401 | Authentication | No - requires fixing timestamp issue | + +## Quick Fix + +- Enable `queryTime: true` in your Ably client options to sync with server time +- Ensure your server's system clock is synchronized with NTP +- Generate fresh token requests instead of caching them + +## Error Messages + +You may see one of these messages: +- "Timestamp not current" +- "Timestamp could not be converted to DateTime" (Rust SDK) + +The error includes the timestamp deviation in milliseconds when logged server-side. + +## Common Causes + +1. **Server clock not synchronized** (40% of cases) + - Authentication server's system time has drifted + - NTP service not running or misconfigured + - Container time not synced with host + + +2. **Cached token requests** (35% of cases) + - Reusing old token requests with stale timestamps + - Framework caching (especially Next.js 13+) + - Authentication endpoint returning cached responses + + +3. **Development environment issues** (15% of cases) + - Developer machine has incorrect system time + - Docker containers with time sync problems + - Virtual machine clock drift + + +4. **Network latency** (10% of cases) + - Significant delay between token generation and use + - Mobile networks with high latency + - Temporary network interruptions + + +## Resolution Steps + +1. **Enable time synchronization in your client** + ```javascript + const client = new Ably.Realtime({ + queryTime: true, // Query Ably's server time + key: 'your-api-key' + }); + ``` + + +2. **Fix your server's system time** + ```bash + # Synchronize system time (Linux/Mac) + sudo ntpdate -s time.nist.gov + + # Enable NTP synchronization + sudo systemctl enable ntp + ``` + + +3. **Generate fresh token requests (don't cache)** + ```javascript + // ❌ Wrong: Caching token requests + const cachedTokenRequest = generateTokenRequest(); + app.get('/auth', (req, res) => res.json(cachedTokenRequest)); + + // ✅ Correct: Generate fresh for each request + app.post('/auth', (req, res) => { + const tokenRequest = ably.auth.createTokenRequest({ + timestamp: Date.now(), // Always use current time + clientId: req.user.id + }); + res.json(tokenRequest); + }); + ``` + + +4. **For Next.js applications** + ```javascript + // Use POST to prevent caching + export async function POST(request) { + const tokenRequest = await ably.auth.createTokenRequest({ + timestamp: Date.now(), + clientId: await getUserId(request) + }); + return Response.json(tokenRequest); + } + + // Disable segment caching + export const dynamic = 'force-dynamic'; + ``` + + +5. **For Docker containers** + ```bash + # Use host time + docker run --volume /etc/localtime:/etc/localtime:ro your-app + ``` + + +## Automatic Handling + +This is an authentication error that SDKs do not automatically retry. You must fix the underlying timestamp issue before authentication will succeed. + +The Ably server validates timestamps are within an acceptable deviation threshold (configurable server-side) to prevent replay attacks. + + +## Prevention + +- **Infrastructure**: Enable NTP synchronization on all servers +- **Application**: Never cache token requests - generate fresh for each authentication +- **Development**: Keep local machine time accurate and sync Docker containers +- **Monitoring**: Set up alerts for time drift on your servers + + +## Related Resources + +- [Token Authentication Guide](https://ably.com/docs/auth/token) +- [Client Options Documentation](https://ably.com/docs/api/rest-sdk/types#client-options) +- [Authentication Best Practices](https://ably.com/docs/auth/security) +- Related errors: [40101](./40101-invalid-api-key.mdx), [40102](./40102-token-expired.mdx) + +## Need Further Help? + +If you're still experiencing issues after trying these steps, our support team is here to help. + +**Contact Ably Support**: https://ably.com/support + +When contacting support, please provide: +- Your account ID and app ID +- The full error message including error code 40104 +- Steps to reproduce the issue +- Any relevant code snippets (without sensitive credentials) +- The SDK and version you're using + +Our team will help you resolve this issue as quickly as possible. + + + + + + + + + + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/40106-missing-authentication-credentials.mdx b/src/pages/docs/platform/errors/codes/40106-missing-authentication-credentials.mdx new file mode 100644 index 0000000000..b9150b0b34 --- /dev/null +++ b/src/pages/docs/platform/errors/codes/40106-missing-authentication-credentials.mdx @@ -0,0 +1,222 @@ + + + + + + + + +# Error 40106: Missing authentication credentials + +## What Happened + +The Ably SDK cannot find the authentication credentials needed to connect to Ably or perform the requested operation. + +## Quick Reference + +| Error Code | HTTP Status | Category | Retryable | +|------------|-------------|----------|-----------| +| 40106 | 400/401/404 | Client Error (Authentication) | No - requires fixing credentials | + +## Quick Fix + +- Provide an API key when initializing the Ably client +- Or configure token authentication with authUrl or authCallback +- Check environment variables are properly set in production + +## Error Messages + +You'll see one of these messages: +- "Auth.requestToken(): options must include valid authentication parameters" +- "Auth Key cannot be empty" +- "No authentication options provided; need one of: key, authUrl, or authCallback (or for testing only, token or tokenDetails)" +- "API key is required to create signed token requests" +- "Unable to obtain credentials from given parameters" + +## Common Causes + +1. **Missing API key** (60% of cases) + + - No key provided during client initialization + - Empty string passed as API key + - Environment variable not set + +2. **Incomplete token authentication setup** (25% of cases) + + - Missing authUrl or authCallback for token auth + - Trying to request a token without proper credentials + - Attempting to use a token to request another token + +3. **Environment configuration issues** (10% of cases) + + - API key not set in production environment + - Docker containers missing environment variables + - Configuration files not loaded correctly + +4. **Wrong authentication method** (5% of cases) + + - Trying to create signed token requests without an API key + - Mixing authentication methods incorrectly + +## Resolution Steps + +1. **For basic authentication: Add your API key** + + ```javascript + // ❌ Wrong: Missing key + const ably = new Ably.Realtime({}); + + // ✅ Correct: With API key + const ably = new Ably.Realtime({ + key: 'your-app-id.your-key-id:your-key-secret' + }); + ``` + +2. **For token authentication: Configure token source** + + ```javascript + // Option 1: Auth URL + const ably = new Ably.Realtime({ + authUrl: '/auth' + }); + + // Option 2: Auth callback + const ably = new Ably.Realtime({ + authCallback: async (tokenParams, callback) => { + const token = await fetchTokenFromYourServer(tokenParams); + callback(null, token); + } + }); + ``` + +3. **For environment variables: Set and verify** + + ```bash + # Set environment variable + export ABLY_API_KEY="your-app-id.your-key-id:your-key-secret" + ``` + + ```javascript + // Use in application + const ably = new Ably.Realtime({ + key: process.env.ABLY_API_KEY + }); + ``` + +4. **Verify your API key format** + + - Check the key follows the format: `app-id.key-id:key-secret` + - Ensure no extra spaces or line breaks + - Verify the key hasn't expired or been revoked in your dashboard + +5. **For server-side token generation** + + ```javascript + // Server endpoint to generate tokens + app.post('/auth', async (req, res) => { + const ably = new Ably.Rest({ key: process.env.ABLY_API_KEY }); + const tokenRequest = await ably.auth.createTokenRequest(); + res.json(tokenRequest); + }); + ``` + +## Automatic Handling + +This is a configuration error that will not be automatically retried. You must provide valid authentication credentials before the operation will succeed. + + +## Prevention + +- Store API keys in environment variables, not in code + +- Validate authentication configuration at application startup + +- Use configuration templates for different environments + +- Test authentication setup in all deployment environments + + +## Platform-Specific Notes + +### JavaScript/Node.js +The error typically occurs during client initialization. Ensure your API key or authentication method is configured before creating the client. + +### Java + +Validates during `requestToken()` calls. Requires authCallback, authUrl, or key. + +### .NET + +Checks authentication during both AuthOptions construction and auth method creation. May return different HTTP status codes (401 or 404) depending on context. + +### Rust + +Validates API key specifically when creating signed token requests. + +## Related Resources + +- [Authentication documentation](https://ably.com/docs/auth) +- [Basic authentication guide](https://ably.com/docs/auth/basic) +- [Token authentication guide](https://ably.com/docs/auth/token) +- [Client options reference](https://ably.com/docs/api/realtime-sdk/client-options) + +## Need Further Help? + +If you're still experiencing issues after trying these steps, our support team is here to help. + +**Contact Ably Support**: https://ably.com/support + +When contacting support, please provide: +- Your account ID and app ID +- The full error message including error code 40106 +- Steps to reproduce the issue +- Any relevant code snippets (without sensitive credentials) +- The SDK and version you're using + +Our team will help you resolve this issue as quickly as possible. + + + + + + + + + + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/40113-account-blocked.mdx b/src/pages/docs/platform/errors/codes/40113-account-blocked.mdx new file mode 100644 index 0000000000..056999bdc8 --- /dev/null +++ b/src/pages/docs/platform/errors/codes/40113-account-blocked.mdx @@ -0,0 +1,176 @@ + + + + + + + + +# Error 40113: Account blocked + +## What Happened + +Your Ably account has been blocked or suspended, preventing all access to Ably services. + +## Quick Reference + +| Error Code | HTTP Status | Category | Retryable | +|------------|-------------|----------|-----------| +| 40113 | 401 | Client Error (Authentication) | No - requires account unblocking | + +## Quick Fix + +- Check your Ably dashboard for account status notifications +- Review recent emails from Ably support +- Contact Ably support immediately at https://ably.com/support + +## Error Messages + +You may see one of these messages: +- "Account blocked" +- "Account [account-id] blocked" +- Custom blocking message with specific details + +## Common Causes + +1. **Payment issues** (most common) + - Failed payment or expired card + - Account delinquency + - Billing disputes + + +2. **Terms of Service violations** + - Excessive usage beyond plan limits + - Abuse or unusual activity patterns + - Security concerns + + +3. **Administrative actions** + - Manual blocking by Ably support + - Automated fraud prevention triggers + - Temporary suspension pending verification + + +## Resolution Steps + +1. **Check account status** + - Log into your [Ably dashboard](https://ably.com/dashboard) + - Look for any account status notifications or warnings + - Review your account settings and billing information + + +2. **Review recent communications** + - Check email for notifications from Ably support + - Look for billing alerts or payment failure notices + - Review any security or compliance communications + + +3. **Contact Ably support immediately** + - This error requires direct intervention from Ably support + - Visit https://ably.com/support to open a ticket + - Be prepared to: + - Provide your account ID + - Explain your use case and recent activities + - Verify account ownership or business details + + +4. **Address the root cause** + - If payment-related: Update billing information + - If usage-related: Review and adjust your usage patterns + - If security-related: Work with support to verify your account + + +## Automatic Handling + +This is a terminal authentication error that will not be automatically retried by Ably SDKs. All API operations will fail until the account status is restored. + + +## Prevention + +- Keep your payment information up to date +- Monitor your account usage against plan limits +- Ensure compliance with [Ably's Terms of Service](https://ably.com/terms) +- Implement proper rate limiting in your applications +- Follow security best practices for API key management +- Set up billing alerts in your dashboard + + +## Connection State Impact + +When this error occurs: +- All existing connections will be terminated +- New connection attempts will fail immediately +- Token generation will be blocked +- All channels and presence will be unavailable + + +## Related Resources + +- [Ably Account Management](https://ably.com/docs/account) +- [Ably Terms of Service](https://ably.com/terms) +- [Ably Pricing and Plans](https://ably.com/pricing) +- [Authentication documentation](https://ably.com/docs/auth) +- Related errors: [40300](./40300-account-restricted.md) (Account restricted) + +## Need Further Help? + +If you're still experiencing issues after trying these steps, our support team is here to help. + +**Contact Ably Support**: https://ably.com/support + +When contacting support, please provide: +- Your account ID and app ID +- The full error message including error code 40113 +- Steps to reproduce the issue +- Any relevant code snippets (without sensitive credentials) +- The SDK and version you're using + +Our team will help you resolve this issue as quickly as possible. + + + + + + + + + + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/40115-account-request-limit-exceeded.mdx b/src/pages/docs/platform/errors/codes/40115-account-request-limit-exceeded.mdx new file mode 100644 index 0000000000..046cbc72d5 --- /dev/null +++ b/src/pages/docs/platform/errors/codes/40115-account-request-limit-exceeded.mdx @@ -0,0 +1,183 @@ + + + + + + + + +# Error 40115: Account request limit exceeded + +## What Happened + +Your Ably account has exceeded its allocated API request quota, triggering a hard limit that temporarily blocks further requests. + +## Quick Reference + +| Error Code | HTTP Status | Category | Retryable | +|------------|-------------|----------|-----------| +| 40115 | 401 | Client Error (Authentication/Limits) | No - requires quota increase or waiting for limit reset | + +## Quick Fix + +- Check your current usage against account limits in the Ably dashboard +- Wait for the limit window to reset (hourly for most limits) +- Contact Ably support to request a quota increase if needed + +## Error Messages + +You may see one of these messages: +- "account restricted request limit exceeded" +- "Account request limit exceeded (err: 40115)" +- "401 Unauthorized: Account quota exceeded" + +## Common Causes + +1. **Hourly request limit exceeded** (70% of cases) + - Account has made more API requests than allowed in the current hour + - Common during traffic spikes or inefficient polling patterns + - Affects all apps under the account + + +2. **Instantaneous rate limit breached** (20% of cases) + - Too many requests sent in a short burst + - Can trigger even if hourly quota isn't exceeded + - Often caused by retry storms or parallel batch operations + + +3. **Account restrictions applied** (10% of cases) + - Free tier limits reached + - Account placed under restriction due to billing issues + - Test accounts with intentionally low limits + + +## Resolution Steps + +1. **Check your current usage** + - Log into your [Ably dashboard](https://ably.com/dashboard) + - Navigate to your account → "Usage" tab + - Review API request metrics against your limits + + +2. **Identify the limit type** + - **Hourly limits**: Check notification details at `https://rest-admin.ably.io/accounts/{accountId}/notifications` + - Look for `apiRequests.hourly.hard` or `apiRequests.maxRate.hard` in the notification + - Hourly limits reset at the top of each hour + + +3. **Reduce request volume** + - Implement request batching where possible + - Use Ably's bulk publish for multiple messages + - Switch from polling to push subscriptions for realtime data + - Cache frequently accessed data + + +4. **Request quota increase** + - Contact [Ably support](https://ably.com/support) with: + - Your account ID + - Current usage patterns + - Expected future requirements + - Provide business justification for increased limits + + +## Automatic Handling + +This is a hard limit error that SDKs cannot automatically retry. Your application must: +- Implement appropriate error handling +- Consider backing off requests until the limit window resets +- Monitor usage to prevent hitting limits + +## Prevention + +- **Monitor usage proactively**: Set up alerts before reaching limits +- **Optimize API usage**: Use bulk operations and avoid unnecessary requests +- **Implement client-side caching**: Reduce redundant API calls +- **Use realtime subscriptions**: Replace polling patterns with push updates +- **Plan for growth**: Request limit increases before major launches + + +## Important Notes + +This error code has been historically overloaded with multiple meanings: +- **Primary usage**: Account request limit exceeded (documented here) +- **Secondary usage**: Maximum number of apps exceeded (returns 400, not 401) +- **Test usage**: App-specific authentication errors + +The primary production usage is for request limit scenarios as described above. + + +## Related Resources + +- [Ably Rate Limits Documentation](https://ably.com/docs/general/limits) +- [Account Management](https://ably.com/docs/general/account) +- [Best Practices for API Usage](https://ably.com/docs/best-practice) +- Related errors: [42920](./42920-rate-limit-exceeded.md) (per-second rate limits) + +## Need Further Help? + +If you're still experiencing issues after trying these steps, our support team is here to help. + +**Contact Ably Support**: https://ably.com/support + +When contacting support, please provide: +- Your account ID and app ID +- The full error message including error code 40115 +- Steps to reproduce the issue +- Any relevant code snippets (without sensitive credentials) +- The SDK and version you're using + +Our team will help you resolve this issue as quickly as possible. + + + + + + + + + + + + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/40121-token-revocation-not-enabled.mdx b/src/pages/docs/platform/errors/codes/40121-token-revocation-not-enabled.mdx new file mode 100644 index 0000000000..7d941e251d --- /dev/null +++ b/src/pages/docs/platform/errors/codes/40121-token-revocation-not-enabled.mdx @@ -0,0 +1,154 @@ + + + + + + + + +# Error 40121: Token revocation not enabled + +## What Happened + +You attempted to use token revocation features that are not enabled for your Ably application or account. + +## Quick Reference + +| Error Code | HTTP Status | Category | Retryable | +|------------|-------------|----------|-----------| +| 40121 | 401 or 400 | Client Error (Authentication) | No - requires configuration change | + +## Quick Fix + +- Check if token revocation is included in your account plan +- Contact your account manager to enable token revocation features +- Use token expiration and renewal as an alternative security approach + +## Error Messages + +You may see one of these messages: +- "Token revocation not enabled for this application" +- "Revocation by channel not enabled for this account" + +## Common Causes + +1. **Token revocation not enabled for application** (most common) + - Your application hasn't been configured with revocation channels + - Token revocation feature not activated for your application + + +2. **Channel-based revocation not enabled** + - Attempting to revoke tokens by channel without the feature flag + - Account doesn't have `revocationByChannel` feature enabled + + +3. **Plan limitations** + - Current account plan doesn't include token revocation features + - Advanced security features require plan upgrade + + +## Resolution Steps + +1. **Check your account features** + - Review your current Ably plan to see if token revocation is included + - Visit your [Ably dashboard](https://ably.com/dashboard) to check account features + - Review [Ably pricing plans](https://ably.com/pricing) for feature availability + + +2. **Enable token revocation for your account** + - Contact Ably support to enable token revocation features + - Your account manager can help activate advanced security features + - Once enabled, configure revocation settings in your application dashboard + + +3. **Configure application settings** + - Set up revocation configuration in your app settings + - Enable channel-based revocation if needed for your use case + - Ensure revocation channels are properly configured + + +4. **Use alternative security approaches** + - Implement shorter token expiration times (TTL) + - Use capability-based access control to restrict token permissions + - Set up token refresh mechanisms for better security + - Monitor token usage patterns for anomaly detection + + +## Automatic Handling + +This is a configuration error that will not be automatically retried. You must enable the feature or use alternative approaches before the operation will succeed. + +## Prevention + +- Review account features and limitations during application planning +- Understand security requirements before implementation +- Consider token lifecycle management in your application design +- Plan for appropriate account tier based on security needs + + +## Related Resources + +- [Token Authentication documentation](https://ably.com/docs/auth/token) +- [Authentication Guide](https://ably.com/docs/auth) +- [Ably Pricing Plans](https://ably.com/pricing) +- Related errors: [40101](https://help.ably.io/error/40101), [40102](https://help.ably.io/error/40102) + +## Need Further Help? + +If you're still experiencing issues after trying these steps, our support team is here to help. + +**Contact Ably Support**: https://ably.com/support + +When contacting support, please provide: +- Your account ID and app ID +- The full error message including error code 40121 +- Steps to reproduce the issue +- Any relevant code snippets (without sensitive credentials) +- The SDK and version you're using + +Our team will help you resolve this issue as quickly as possible. + + + + + + + + + + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/40130-key-removed.mdx b/src/pages/docs/platform/errors/codes/40130-key-removed.mdx new file mode 100644 index 0000000000..10775d73a2 --- /dev/null +++ b/src/pages/docs/platform/errors/codes/40130-key-removed.mdx @@ -0,0 +1,177 @@ + + + + + + + + +# Error 40130: Key removed + +## What Happened + +The API key you're using has been permanently removed from your Ably account and cannot be restored. + +## Quick Reference + +| Error Code | HTTP Status | Category | Retryable | +|------------|-------------|----------|-----------| +| 40130 | 401 | Client Error (Authentication) | No - key permanently deleted | + +## Quick Fix + +- Stop all operations using this key immediately +- Log into your [Ably dashboard](https://ably.com/dashboard) to create a new API key +- Update your application with the new key credentials + +## Error Messages + +You may see this error message: +- "Key removed" + +## Common Causes + +1. **Administrative key removal** (60% of cases) + - Key deleted through the Ably dashboard + - Bulk key cleanup operations + - App restructuring or deletion + + +2. **Security-driven removal** (30% of cases) + - Compromised key deletion + - Security incident response + - Preventive key rotation with deletion + + +3. **Account management changes** (10% of cases) + - Key management policy changes + - Compliance-driven key removal + - Account reorganization + + +## Resolution Steps + +1. **Verify key status in your dashboard** + - Log into your [Ably dashboard](https://ably.com/dashboard) + - Navigate to your app → "API Keys" tab + - Confirm the key was removed (it won't appear in the list) + + +2. **Create a replacement API key** + - Click "Create a new API key" in the dashboard + - Configure the same capabilities as your original key + - Copy the complete key including the app ID prefix + + +3. **Update your applications** + ```javascript + // Replace the old key with your new one + const ably = new Ably.Realtime('YOUR_NEW_API_KEY'); + ``` + + - Update all configuration files and environment variables + - Replace the key in all client applications + - Test connections with the new key + + +4. **Audit all key usage locations** + - Review where the removed key was being used + - Check server applications, mobile apps, and web clients + - Monitor for any authentication failures from missed updates + + +## Automatic Handling + +This is a permanent authentication failure that will not be automatically retried by Ably SDKs. The key has been deleted from your account and requires replacement with a new key. + + +## Prevention + +- Implement proper key lifecycle management +- Use environment variables for key storage +- Maintain documentation of key usage across applications +- Set up monitoring for authentication failures +- Follow key rotation best practices without deleting active keys + + +## Security Considerations + +If the key was removed due to security concerns: +- Audit recent account activity for unusual patterns +- Review access logs for any unauthorized usage +- Consider rotating other keys as a precaution +- Update security policies and procedures + + +## Important Note + +Unlike revoked keys (error 40131) or expired keys (error 40132), removed keys cannot be restored. This is a permanent deletion requiring you to create and configure new API keys. + + +## Related Resources + +- [API Key Management](https://ably.com/docs/auth/api-key) +- [Authentication Guide](https://ably.com/docs/auth) +- [Basic Authentication](https://ably.com/docs/auth/basic) +- Related errors: [40131 (Key revoked)](./40131-key-revoked.mdx), [40132 (Key expired)](./40132-key-expired.mdx) + +## Need Further Help? + +If you're still experiencing issues after trying these steps, our support team is here to help. + +**Contact Ably Support**: https://ably.com/support + +When contacting support, please provide: +- Your account ID and app ID +- The full error message including error code 40130 +- Steps to reproduce the issue +- Any relevant code snippets (without sensitive credentials) +- The SDK and version you're using + +Our team will help you resolve this issue as quickly as possible. + + + + + + + + + + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/40131-key-revoked.mdx b/src/pages/docs/platform/errors/codes/40131-key-revoked.mdx new file mode 100644 index 0000000000..a3b4cf7cc3 --- /dev/null +++ b/src/pages/docs/platform/errors/codes/40131-key-revoked.mdx @@ -0,0 +1,202 @@ + + + + + + + + +# Error 40131: Key revoked + +## What Happened +Your API key has been temporarily suspended (revoked) and cannot be used for authentication until it's restored by an administrator. + +## Quick Reference +| Error Code | HTTP Status | Category | Retryable | +|------------|-------------|----------|-----------| +| 40131 | 401 | Client Error (Authentication) | No - requires administrative action | + +## Quick Fix +- Check the API key status in your Ably dashboard +- Contact your account administrator about the revoked key +- Switch to an alternative API key if available + +## Error Messages + +You may see one of these messages: +- "Key revoked (err: 40131)" +- "TokenDetails request failed with error: Error 40131 - Key revoked" +- "ARTPushActivationStateMachine: update device failed Key revoked" + +## Common Causes + +1. **Administrative suspension** (60% of cases) + + - Key temporarily suspended through dashboard + - Precautionary revocation pending review + - Policy compliance measures + +2. **Security concerns** (25% of cases) + + - Suspected key compromise + - Unusual usage patterns detected + - Temporary suspension during investigation + +3. **Account management** (15% of cases) + + - Key rotation process with temporary revocation + - Access control changes + - Compliance-related suspension + +## Resolution Steps + +1. **Check your API key status** + + - Log into your [Ably dashboard](https://ably.com/dashboard) + - Navigate to your app → "API Keys" tab + - Look for the key status and any associated messages + +2. **Contact your account administrator** + + - If you're not the account owner, reach out to your admin or team lead + - Explain when the error started occurring + - Provide the affected API key prefix for identification + +3. **For account administrators: Contact support** + + - If you're the admin and didn't revoke the key, contact Ably support + - Provide context about the key usage and any recent changes + - Include any security notifications you may have received + +4. **Use an alternative key temporarily** + + - If available, switch to a backup API key + - Generate a new key if restoration isn't immediately possible + - Update your application configuration with the new credentials + +## Automatic Handling +This is a client error that will not be automatically retried. The API key must be restored or replaced before authentication will succeed. + +## Common Troubleshooting Scenarios + +### CI/CD Pipeline Failures + +If your automated tests or deployments are failing with this error: +- API keys used in CI/CD may have been revoked during security reviews +- Generate dedicated keys for CI/CD environments +- Store CI/CD keys securely in environment secrets + +### Push Notification Issues + +If device registration or push updates are failing: +- This error can affect push notification device registration +- The error message may appear as "ARTPushActivationStateMachine: update device failed" +- Ensure the key used for push services has not been revoked + +### Token Generation Failures + +When generating tokens fails with this error: +- A revoked key cannot generate new tokens +- This affects both direct token requests and token authentication flows +- Switch to a valid key for token generation + +## Key Revoked vs Other Key States + +**Key Revoked (40131)** - Different from other key errors: + +- **Can be restored**: Unlike removed keys (40130), revoked keys can be re-enabled +- **Temporary suspension**: Not a permanent deletion +- **Maintains configuration**: Original key settings are preserved +- **Administrative action**: Requires account admin or support intervention + +**Related errors**: +- Error 40130 (Key removed): Permanent deletion, cannot be restored +- Error 40132 (Key expired): Time-based expiration, requires new key +- Error 40133 (Key disabled): Administrative disable, different from revocation + +## Prevention + + +- Monitor key usage patterns and alerts in your dashboard +- Implement proper key lifecycle management +- Use different keys for different environments (development, staging, production) +- Set up monitoring for authentication failures +- Follow [security best practices](https://ably.com/docs/auth#security-best-practice) for key storage + +## Related Resources +- [API Key Management](https://ably.com/docs/auth#api-key-authentication) +- [Token Authentication](https://ably.com/docs/auth#token-authentication) +- [Security Best Practices](https://ably.com/docs/auth#security-best-practice) + +## Need Further Help? + +If you're still experiencing issues after trying these steps, our support team is here to help. + +**Contact Ably Support**: https://ably.com/support + +When contacting support, please provide: +- Your account ID and app ID +- The full error message including error code 40131 +- Steps to reproduce the issue +- Any relevant code snippets (without sensitive credentials) +- The SDK and version you're using + +Our team will help you resolve this issue as quickly as possible. + + + + + + + + + + + + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/40132-api-key-expired.mdx b/src/pages/docs/platform/errors/codes/40132-api-key-expired.mdx new file mode 100644 index 0000000000..9a26e7f52f --- /dev/null +++ b/src/pages/docs/platform/errors/codes/40132-api-key-expired.mdx @@ -0,0 +1,211 @@ + + + + + + + + +# Error 40132: API key expired + +## What Happened + +Your API key has reached its expiration date and can no longer be used for authentication with Ably services. + +## Quick Reference + +| Error Code | HTTP Status | Category | Retryable | +|------------|-------------|----------|-----------| +| 40132 | 401 | Authentication (Key Management) | No - requires new API key | + +## Quick Fix + +- Generate a new API key in your Ably dashboard +- Replace the expired key in all applications and services +- Verify connections work with the new key + +## Error Messages + +You may see this error message: +- "Key expired" + +## Common Causes + +1. **Scheduled expiration** (80% of cases) + - Key reached its predetermined expiration date + - Time-based security policies automatically enforced + - Automated key lifecycle management triggered expiration + + +2. **Forgotten renewal** (15% of cases) + - Key expiration date not tracked or monitored + - Manual renewal process overlooked + - No calendar reminders or monitoring alerts configured + + +3. **Policy changes** (5% of cases) + - Security compliance requirements shortened key lifetimes + - Organizational key management policies updated + - Retroactive policy changes affecting existing keys + + +## Resolution Steps + +1. **Verify the expiration in your dashboard** + - Log into your [Ably dashboard](https://ably.com/dashboard) + - Navigate to your app → "API Keys" tab + - Identify the expired key and confirm its expiration date + + +2. **Generate a replacement API key** + - Click "Create a new API key" in the dashboard + - Configure the same capabilities as your expired key + - Set an appropriate expiration date for the new key + - Copy the complete key (including the app ID prefix) + - Store the new key securely + + +3. **Update your applications** + - Replace the expired key in all client applications + - Update configuration files and environment variables + - Deploy changes to all environments (development, staging, production) + - Document the key change in your deployment logs + + +4. **Test the new key** + - Verify connections work with the new key + - Test all affected applications and services + - Monitor for any authentication errors + - Check that all integrations are functioning correctly + + +## Automatic Handling + +This is an authentication error that will not be automatically retried by Ably SDKs. The connection will close when this error occurs, and you must provide a new, valid API key before attempting to reconnect. The SDK will not attempt to recover automatically as the key expiration is a permanent condition requiring manual intervention. + + +## Prevention + +To avoid API key expiration issues: + +- **Set up monitoring**: Configure alerts for upcoming key expirations (30-60 days in advance) +- **Use calendar reminders**: Create recurring reminders before expiration dates +- **Implement key rotation**: Establish a regular key renewal schedule +- **Document expiration dates**: Maintain centralized records of all key expiration dates +- **Consider longer expiration periods**: Balance security requirements with operational convenience +- **Automate where possible**: Use automation tools for key rotation in non-production environments + + +### Best Practices for Key Rotation + +1. **Plan ahead**: Renew keys 30-60 days before expiration +2. **Stage deployments**: Update non-production environments first +3. **Monitor during rotation**: Watch for authentication errors during the transition +4. **Keep backup keys**: Have replacement keys ready for immediate use +5. **Update documentation**: Ensure all key references are updated +6. **Test thoroughly**: Verify all services after key rotation + + +## Long-Running Applications + +For applications that run continuously: +- Implement key refresh mechanisms before expiration +- Monitor for authentication errors proactively +- Set up automated restart procedures for key updates +- Consider using token authentication with automatic renewal for better key management +- Plan maintenance windows for key rotation if necessary + + +## Connection State Impact + +When this error occurs: +- The connection enters the `failed` state +- Automatic reconnection will NOT occur +- All channel subscriptions are terminated +- Presence members are removed +- You must create a new connection with valid credentials + +Monitor connection state to detect this error: +```javascript +ably.connection.on('failed', (stateChange) => { + if (stateChange.reason?.code === 40132) { + console.log('API key expired - update credentials'); + // Implement key refresh logic + } +}); +``` + + +## Related Resources + +- [API Key Management](https://ably.com/docs/auth/api-key) +- [Authentication Guide](https://ably.com/docs/auth) +- [Token Authentication](https://ably.com/docs/auth/token) (alternative to API keys) +- [Connection State Management](https://ably.com/docs/realtime/connection) +- Related errors: [40131 - Key revoked](./40131-key-revoked), [40133 - Key disabled](./40133-key-disabled) + +## Need Further Help? + +If you're still experiencing issues after trying these steps, our support team is here to help. + +**Contact Ably Support**: https://ably.com/support + +When contacting support, please provide: +- Your account ID and app ID +- The full error message including error code 40132 +- Steps to reproduce the issue +- Any relevant code snippets (without sensitive credentials) +- The SDK and version you're using + +Our team will help you resolve this issue as quickly as possible. + + + + + + + + + + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/40133-token-revocation-authorization-error.mdx b/src/pages/docs/platform/errors/codes/40133-token-revocation-authorization-error.mdx index b994cdea28..df5f2a7e62 100644 --- a/src/pages/docs/platform/errors/codes/40133-token-revocation-authorization-error.mdx +++ b/src/pages/docs/platform/errors/codes/40133-token-revocation-authorization-error.mdx @@ -1,7 +1,7 @@ - + 2. **Configuration errors** (15% of cases) - Incorrect key selection in revocation requests - Mixed up key IDs in multi-environment setups - Copy-paste errors when setting up revocation requests + 3. **Process confusion** (5% of cases) - Not tracking which key issued which tokens - Attempting bulk revocation with a single key for tokens from multiple keys - Misunderstanding the token-key relationship requirements + ## Resolution Steps @@ -68,18 +71,19 @@ You'll see this exact message: const ably = new Ably.Rest({ key: 'originalKey.id:secret' }); await ably.auth.revokeTokens({ keyName: 'originalKey.id' }); ``` - + 3. **Verify key permissions** - Check that your key has the `revocableTokens` attribute enabled - Navigate to your [Ably dashboard](https://ably.com/dashboard) → API Keys - Confirm the key has token revocation capabilities - + 4. **Test the revocation** - Attempt revocation with the correct key - Verify tokens are successfully invalidated - Monitor for successful revocation confirmation + ## Automatic Handling @@ -135,31 +139,31 @@ Our team will help you resolve this issue as quickly as possible. - Analysis File: https://github.com/ably/ably-os/blob/main/output/error-codes/research/40133-analysis.md - Knowledge File: https://github.com/ably/ably-os/blob/main/output/error-codes/research/40133-knowledge.md - Editorial Notes: https://github.com/ably/ably-os/blob/main/src/prompts/errors/editorial-notes.md [No specific error-specific notes for 40133] -- Existing Documentation: None found - this is new documentation +- Existing Documentation: https://github.com/ably/docs/blob/main/src/pages/docs/platform/errors/codes/40133-token-revocation-authorization-error.mdx [Enhanced from existing version] --> - + - + # Error 40140: Token error (unspecified) @@ -27,6 +27,7 @@ Your authentication token could not be validated, and the specific reason couldn - Request a new authentication token from your server - Verify your token generation process is working correctly - Check that your token hasn't expired or been revoked +- Ensure token has required permissions for the operation ## Error Messages @@ -40,21 +41,31 @@ You may see one of these messages: 1. **Expired token** (most common) - Token has exceeded its TTL (time to live) - Token was valid when created but expired during use + - Default TTL is 60 minutes unless specified differently 2. **Invalid token format** - Token structure is corrupted or malformed - Token was incorrectly generated or transmitted + - Missing required fields in token payload 3. **Permission issues** - Token lacks required capabilities for the operation - Token was created with insufficient permissions - + - Channel requires capabilities not present in token + -4. **Unspecified token problem** +4. **Stale cached token** + - SDK using outdated token from cache + - Token was revoked but still cached locally + - Token refresh failed to update cached credentials + + +5. **Unspecified token problem** - Generic token validation failure - System couldn't determine the specific token issue + - Catch-all for uncommon token problems ## Resolution Steps @@ -63,21 +74,45 @@ You may see one of these messages: - Have your server generate a fresh authentication token - Ensure the token includes all required capabilities - Replace the expired/invalid token in your client + - Verify the new token works with a simple API call 2. **Verify token generation** - Check your server-side token creation logic - Ensure you're using the correct API key for token generation - Verify the token request parameters are correct + - Confirm TTL is appropriate for your use case -3. **Implement token refresh** +3. **Check required capabilities** + - Verify token has permissions for the channel and operation + - Add required capabilities when generating tokens: + ```javascript + const tokenRequest = await ably.auth.createTokenRequest({ + capability: { + 'channel-name': ['publish', 'subscribe', 'presence'] + } + }); + ``` + + +4. **Implement token refresh** - Set up automatic token renewal before expiration - Monitor token TTL and refresh proactively - Handle token errors gracefully in your application + - Use auth callbacks for automatic renewal: + ```javascript + const ably = new Ably.Realtime({ + authCallback: async (tokenParams, callback) => { + // Fetch new token from your server + const tokenRequest = await fetchTokenFromServer(); + callback(null, tokenRequest); + } + }); + ``` -4. **For SSE connections** +5. **For SSE connections specifically** ```javascript eventSource.onerror = msg => { const err = JSON.parse(msg.data); @@ -85,6 +120,9 @@ You may see one of these messages: if(isTokenErr) { eventSource.close(); // Fetch new token and reconnect + const newToken = await fetchNewToken(); + const newUrl = `${baseUrl}?access_token=${newToken}`; + eventSource = new EventSource(newUrl); } } ``` @@ -93,25 +131,48 @@ You may see one of these messages: ## Automatic Handling Ably SDKs automatically detect token errors in the 40140-40149 range and: -- Clear any cached token details to prevent reuse -- Attempt to obtain a new token if a token callback is configured +- Clear any cached token details to prevent reuse of invalid tokens +- Attempt to obtain a new token if an auth callback is configured - Will not automatically retry without a valid token - +- Trigger token refresh logic when auth callbacks are set up + +The SDK's behavior varies slightly by implementation: +- **JavaScript**: Uses `isTokenErr()` function for range detection +- **Java**: Clears token cache and checks for stale tokens specifically +- **Python**: Uses `is_token_error()` helper for classification + ## Prevention -- **Implement proactive token refresh**: Renew tokens before they expire +- **Implement proactive token refresh**: Renew tokens before they expire (e.g., at 75% of TTL) - **Monitor token lifecycle**: Track token creation and expiration times -- **Use appropriate TTLs**: Balance security with user experience +- **Use appropriate TTLs**: Balance security with user experience (default 60 minutes) - **Handle the 40140-40149 range**: Set up specific error handling for all token errors - +- **Use auth callbacks**: Let the SDK handle token renewal automatically +- **Clear token cache on errors**: Ensure stale tokens aren't reused + + +## Understanding the Token Error Range + +Error 40140 is the first in a range of token-related errors (40140-40149): +- **40140**: Unspecified token error (this error) +- **40141**: Token has been revoked +- **40142**: Token has expired +- **40143**: Token is unrecognized +- **40144**: Invalid JWT format +- **40145**: Invalid token format +- **40146-40149**: Reserved for future token errors + +All errors in this range require obtaining a new, valid token to resolve. + ## Related Resources - [Token Authentication Documentation](https://ably.com/docs/auth/token) - [Authentication Guide](https://ably.com/docs/auth) - [Token Capabilities](https://ably.com/docs/auth/capabilities) -- Related errors: 40141-40149 (specific token error types) +- [Auth Callbacks](https://ably.com/docs/auth/token#token-refresh) +- Related errors: [40141](./40141-token-revoked.md) through [40149](./40149-token-error.md) (specific token error types) ## Need Further Help? @@ -136,31 +197,48 @@ Our team will help you resolve this issue as quickly as possible. - Analysis File: https://github.com/ably/ably-os/blob/main/output/error-codes/research/40140-analysis.md - Knowledge File: https://github.com/ably/ably-os/blob/main/output/error-codes/research/40140-knowledge.md - Editorial Notes: https://github.com/ably/ably-os/blob/main/src/prompts/errors/editorial-notes.md (Lines 78-84 for token expiration range guidance) -- Existing Documentation: None found - this is new documentation +- Existing Documentation: https://github.com/ably/docs/blob/main/src/pages/docs/platform/errors/codes/40140-token-error-unspecified.mdx (enhanced and improved) --> + + - + - + # Error 40142: Token expired @@ -34,6 +34,7 @@ You may see one of these messages: - "Token expired" - "Token expired. (See https://help.ably.io/error/40142 for help.)" - In SSE/HTTP streams: `event: error data: {"message":"Token expired","code":40142,"statusCode":401}` +- "Key/token status changed expire" (when connection state changes) ## Common Causes @@ -46,7 +47,7 @@ You may see one of these messages: 2. **Missing token refresh mechanism** (15% of cases) - No automatic token renewal implemented - Token refresh not triggered before expiration - - Error handling doesn't include token refresh + - AuthCallback not configured for automatic renewal 3. **Network issues** (5% of cases) @@ -119,6 +120,16 @@ For applications that run continuously: - Use connection state monitoring to detect authentication failures early +## Special Considerations + +### Push Notifications +Token expiration in push notification contexts may relate to either JWT tokens or deviceIdentityTokens. Both produce similar error logs, making diagnosis challenging. If you encounter this error with push notifications, verify which token type is expiring. + + +### Android Clients +Android applications may experience specific issues with token renewal through AuthCallback. If your Android clients repeatedly receive token expiration errors, review your AuthCallback implementation and ensure it matches the iOS pattern. + + ## Related Resources - [Token Authentication documentation](https://ably.com/docs/auth/token) @@ -149,11 +160,13 @@ Our team will help you resolve this issue as quickly as possible. - Analysis File: https://github.com/ably/ably-os/blob/main/output/error-codes/research/40142-analysis.md - Knowledge File: https://github.com/ably/ably-os/blob/main/output/error-codes/research/40142-knowledge.md - Editorial Notes: https://github.com/ably/ably-os/blob/main/src/prompts/errors/editorial-notes.md (No specific error-specific notes for 40142) +- Existing Documentation: https://github.com/ably/docs/blob/main/src/pages/docs/platform/errors/codes/40142-token-expired.mdx (enhanced from existing version) --> - + @@ -88,8 +90,8 @@ You may see one of these messages: 3. **Fix library-specific issues** **For PHP Lcobucci/JWT users:** - Configure the library to use integer timestamps only. By default, it creates timestamps with microseconds which Ably rejects. - + Configure the library to use integer timestamps only. By default, it creates timestamps with microseconds which Ably rejects. See the [library discussion](https://github.com/lcobucci/jwt/discussions/623) for configuration details. + **For Kafka Connect/Confluent integration:** Add these converter configurations: @@ -97,6 +99,12 @@ You may see one of these messages: - `value.converter: org.apache.kafka.connect.converters.ByteArrayConverter` - `value.converter.schemas.enable: false` + + **For Python SDK with auth_url and headers:** + If encountering issues with TokenRequest and authorization headers: + - Option 1: Return a JWT or Ably token instead of TokenRequest + - Option 2: Use auth_callback instead of auth_url + 4. **Test with a minimal valid token** Create a simple token with only required fields to isolate the issue. @@ -119,6 +127,7 @@ This is a client error that will not be automatically retried. You must fix the - Validate tokens after generation using JWT debugging tools - Test your token generation with the specific Ably SDK you're using - Monitor authentication failures during development to catch format issues early +- Be aware of SDK-specific behaviors (Python vs JavaScript differences) ## Related Resources @@ -126,6 +135,7 @@ This is a client error that will not be automatically retried. You must fix the - [Ably JWT Authentication Guide](https://ably.com/docs/auth/token) - [Token Generation Documentation](https://ably.com/docs/auth/token#token-request-process) - [JWT Specification (RFC 7519)](https://tools.ietf.org/html/rfc7519) +- [Lcobucci/JWT Configuration Guide](https://github.com/lcobucci/jwt/discussions/623) - Related errors: [40140](./40140-token-expired), [40141](./40141-token-unrecognized), [40142](./40142-token-revoked) ## Need Further Help? @@ -151,37 +161,46 @@ Our team will help you resolve this issue as quickly as possible. - Analysis File: https://github.com/ably/ably-os/blob/main/output/error-codes/research/40144-analysis.md - Knowledge File: https://github.com/ably/ably-os/blob/main/output/error-codes/research/40144-knowledge.md - Editorial Notes: https://github.com/ably/ably-os/blob/main/src/prompts/errors/editorial-notes.md - No specific error-specific notes for 40144 -- Existing Documentation: None found +- Existing Documentation: https://github.com/ably/docs/blob/main/src/pages/docs/platform/errors/codes/40144-invalid-jwt-token-format.mdx (enhanced from existing) --> + + - + - + -# Error 40146: Unsupported Token Claims +# Error 40146: Unsupported token claims -## What Happened +## What happened -Your token request to Ably's server includes `userClaims` or `limitsClaims`, which are not supported in server-generated tokens. +Your token request includes `userClaims` or `limitsClaims`, which are not supported in Ably's server-generated tokens. -## Quick Reference +## Quick reference | Error Code | HTTP Status | Category | Retryable | |------------|-------------|----------|-----------| | 40146 | 401 | Client Error (Authentication) | No - requires removing unsupported claims or switching to client-side token generation | -## Quick Fix +## Quick fix - Remove `userClaims` and `limitsClaims` from your token request -- Use standard token capabilities instead -- Or switch to client-side token generation if you need these features +- Use standard token capabilities for access control instead +- Or generate tokens client-side if you need these advanced JWT features -## Error Messages +## Error messages You'll see this message: - "userClaims and limitsClaims are not currently supported in server-generated tokens" -## Common Causes +## Common causes 1. **Including advanced JWT features in server-side token requests** (most common) - Adding `userClaims` to your token request body @@ -44,16 +44,18 @@ You'll see this message: 2. **Migration from custom token generation** - Moving from client-side to server-side token generation without removing unsupported features - Copy-pasting token request code that includes these claims - + - Assuming all JWT features work with server-side generation + 3. **Documentation misunderstanding** - Mixing examples meant for client-side and server-side token generation - - Assuming all JWT features work with server-side generation - + - Not realizing the feature limitations of server-side generation + - Following tutorials that use client-side generation patterns + -## Resolution Steps +## Resolution steps -### 1. Remove Unsupported Claims +### 1. Remove unsupported claims If these claims aren't essential to your application: @@ -71,77 +73,101 @@ If these claims aren't essential to your application: capability: { '*': ['publish', 'subscribe'] } }); ``` - + -2. **Use standard token features** - - Use `clientId` for user identification - - Use capabilities for access control - - Store user-specific data in your application +2. **Use standard token features instead** + - Use `clientId` for user identification instead of `userClaims` + - Use capabilities for fine-grained access control + - Store user-specific metadata in your application -### 2. Switch to Client-Side Token Generation +### 2. Switch to client-side token generation If you need `userClaims` or `limitsClaims`: -1. **Generate tokens in your application** - - Use a JWT library in your backend - - Sign tokens with your Ably API key +1. **Generate tokens in your application backend** + - Use a JWT library in your server code + - Sign tokens with your Ably API key secret - Include any JWT claims you need -2. **Return signed tokens to clients** - - Your server generates the complete JWT +2. **Return signed JWT tokens to clients** + - Your backend generates the complete JWT - Clients use the token directly with Ably - - Full control over all JWT features + - Full control over all JWT features and claims + +3. **Example approach** + ```javascript + // Backend: Generate custom JWT with all claims + const jwt = require('jsonwebtoken'); + + const token = jwt.sign({ + 'x-ably-capability': JSON.stringify({ '*': ['publish', 'subscribe'] }), + 'x-ably-clientId': 'user-123', + userClaims: { role: 'admin', department: 'engineering' }, + limitsClaims: { maxChannels: 10 } + }, apiKeySecret, { + expiresIn: '1h', + keyid: apiKeyId + }); + + // Return token to client + ``` + -See [Ably's token authentication documentation](https://ably.com/docs/auth/token) for implementation details. +See [Ably's token authentication documentation](https://ably.com/docs/auth/token) for complete implementation details. -### 3. Alternative Approaches +### 3. Alternative approaches -Consider if you actually need these advanced claims: +Consider whether you actually need these advanced claims: -1. **Use token capabilities** for fine-grained access control -2. **Use clientId** to identify users -3. **Store user metadata** in your own database -4. **Implement custom authorization** in your application layer +1. **Use token capabilities** for channel-level access control +2. **Use clientId** to identify and track users +3. **Store user metadata** in your own database and reference via clientId +4. **Implement custom authorization** in your application layer before issuing tokens -## Automatic Handling +## Automatic handling This is a validation error that occurs before token generation. Ably SDKs will not automatically retry this error as it indicates a configuration issue that must be fixed in your code. ## Prevention -- **Understand the difference** between server-side and client-side token generation -- **Check feature support** before implementing token generation -- **Test token generation** in development environments +- **Understand the difference** between server-side and client-side token generation capabilities +- **Check feature support** in documentation before implementing token generation +- **Test token generation** in development environments first - **Choose the appropriate method** based on your feature requirements -## Token Generation Methods Comparison +## Token generation methods comparison -### Server-Side Generation (Ably-Managed) -- Simpler implementation +### Server-side generation (Ably-managed) +- Simpler implementation with less code - Standard JWT claims only - `userClaims` and `limitsClaims` **NOT** supported - Suitable for basic authentication needs -### Client-Side Generation (Self-Managed) +### Client-side generation (self-managed) - Full JWT specification support - `userClaims` and `limitsClaims` supported -- More complex implementation +- More complex implementation required - Complete control over token contents -## Related Resources +## Real-world context + +This error has been encountered in production environments, particularly during Project RARE implementation at Ably, where teams attempted to use advanced JWT features with server-generated tokens. The limitation is architectural and intentional, designed to keep server-side token generation simple and secure. + + +## Related resources -- [Token Authentication](https://ably.com/docs/auth/token) -- [Token Request API](https://ably.com/docs/api/rest-api#token-request) -- [JWT Token Claims](https://ably.com/docs/auth/token#claims) -- [Authentication Guide](https://ably.com/docs/auth) +- [Token authentication](https://ably.com/docs/auth/token) +- [Token request API](https://ably.com/docs/api/rest-api#token-request) +- [JWT token claims](https://ably.com/docs/auth/token#claims) +- [Authentication guide](https://ably.com/docs/auth) - Related errors: [40001](./40001-bad-request.md) (Invalid token request) -## Need Further Help? +## Need further help? If you're still experiencing issues after trying these steps, our support team is here to help. @@ -164,31 +190,32 @@ Our team will help you resolve this issue as quickly as possible. - Analysis File: https://github.com/ably/ably-os/blob/main/output/error-codes/research/40146-analysis.md - Knowledge File: https://github.com/ably/ably-os/blob/main/output/error-codes/research/40146-knowledge.md - Editorial Notes: https://github.com/ably/ably-os/blob/main/src/prompts/errors/editorial-notes.md (No specific error-specific notes for 40146) -- Existing Documentation: None found +- Existing Documentation: https://github.com/ably/docs/blob/main/src/pages/docs/platform/errors/codes/40146-unsupported-token-claims.mdx (enhanced from existing) - Repository Overviews: Not needed for this specific error --> - + - + # Error 40149: Token error range boundary @@ -44,7 +44,7 @@ You may see error messages similar to: 2. **SDK error classification** - SDK identified a token-related authentication failure - - Error fell within the recoverable token error range + - Error fell within the recoverable token error range (40140-40149) 3. **Token lifecycle event** @@ -64,7 +64,7 @@ You may see error messages similar to: - Request a new token from your authentication endpoint - Ensure the new token has the required capabilities - Verify token generation is working correctly - + 3. **Reconnect with the new token** - Close the current connection @@ -123,7 +123,7 @@ Our team will help you resolve this issue as quickly as possible. - Analysis File: https://github.com/ably/ably-os/blob/main/output/error-codes/research/40149-analysis.md - Knowledge File: https://github.com/ably/ably-os/blob/main/output/error-codes/research/40149-knowledge.md - Editorial Notes: https://github.com/ably/ably-os/blob/main/src/prompts/errors/editorial-notes.md (Token expiration range guidance at lines 80-84) -- Existing Documentation: None found +- Existing Documentation: https://github.com/ably/docs/blob/main/src/pages/docs/platform/errors/codes/40149-token-error-range-boundary.mdx (enhanced and updated) - Repository Overviews: Not used for this error --> diff --git a/src/pages/docs/platform/errors/codes/90099-generic-discontinuity.mdx b/src/pages/docs/platform/errors/codes/90099-generic-discontinuity.mdx index 61a6df1cfe..2bfa90f137 100644 --- a/src/pages/docs/platform/errors/codes/90099-generic-discontinuity.mdx +++ b/src/pages/docs/platform/errors/codes/90099-generic-discontinuity.mdx @@ -1,18 +1,18 @@ - + - + # Error 90099: Generic discontinuity -## What Happened? +## What Happened A discontinuity has been detected in the message stream, indicating a gap or break in the sequence of messages on this channel. @@ -36,11 +36,13 @@ You may see one of these messages: ## Common Causes 1. **Artificial discontinuity for testing** (Most common) + - Administrative testing of discontinuity handling - Debug endpoint triggered discontinuity - Simulated message gap for validation 2. **Unspecified discontinuity scenario** + - Generic fallback when specific discontinuity type unknown - Catch-all for unusual continuity breaks @@ -75,6 +77,14 @@ A discontinuity means there's a break in the continuous flow of messages. This c When a discontinuity occurs, you cannot rely on having received all messages in sequence. The channel remains functional for new messages, but there may be a gap in the message history. +## Prevention + +While discontinuities cannot always be prevented, you can minimize their impact: +- Design your application to handle potential message gaps gracefully +- Use persistent message history when message ordering is critical +- Implement state reconciliation mechanisms +- Monitor for discontinuity events and respond appropriately + ## Related Resources - [Message continuity documentation](https://ably.com/docs/realtime/channels#continuity) @@ -104,8 +114,8 @@ Our team will help you resolve this issue as quickly as possible. @@ -118,13 +128,14 @@ Our team will help you resolve this issue as quickly as possible. - + - + # Error 91000: Presence requires client ID @@ -41,23 +41,26 @@ You may see one of these messages: - Creating an Ably client without specifying a client ID - Using basic authentication without setting client ID - Missing client ID in token parameters + - Quick-start implementations often miss this requirement 2. **Anonymous connection attempting presence** (8% of cases) - Default connections don't have client IDs - - Quick-start implementations often miss this requirement - Demo applications without proper authentication setup - + - First-time developers not aware of clientId requirement + 3. **Client ID lost during authentication renewal** (2% of cases) - Token renewal didn't include client ID - JWT token missing client ID claim + - Cached token with outdated client ID ## Resolution Steps 1. **Set client ID in client options** ```javascript + // JavaScript/Node.js example const ably = new Ably.Realtime({ key: 'your-api-key', clientId: 'unique-user-id' // Add this line @@ -67,19 +70,41 @@ You may see one of these messages: 2. **Configure client ID via token authentication** ```javascript + // Request a token with client ID const tokenParams = { clientId: 'unique-user-id' }; const token = await ably.auth.requestToken(tokenParams); + + // Or use token callback + const ably = new Ably.Realtime({ + authCallback: async (tokenParams, callback) => { + const token = await fetchTokenFromServer({ + clientId: 'unique-user-id' + }); + callback(null, token); + } + }); ``` 3. **Use JWT with client ID claim** - - Ensure your JWT includes a client ID in the token claims - - The JWT should be generated server-side with the appropriate client ID + ```javascript + // Server-side JWT generation should include client ID + const jwt = generateJWT({ + 'x-ably-clientId': 'unique-user-id', + // other claims... + }); + + // Client-side usage + const ably = new Ably.Realtime({ + authUrl: '/auth', + authMethod: 'GET' + }); + ``` -4. **Verify client ID is set** +4. **Verify client ID is set before presence operations** ```javascript // Check if client ID is configured console.log('Client ID:', ably.auth.clientId); @@ -87,13 +112,26 @@ You may see one of these messages: // Only attempt presence if client ID exists if (ably.auth.clientId) { await channel.presence.enter(); + } else { + console.error('Client ID required for presence operations'); } ``` ## Automatic Handling -This is a client error that will not be automatically retried. You must configure a client ID before the presence operation will succeed. +This is a client error that will not be automatically retried. You must configure a client ID before the presence operation will succeed. The error is thrown during pre-flight validation before any network request is made. + +## SDK-Specific Behavior + +Different SDKs validate client ID at different points: +- **Go SDK**: Validates on Enter, Update, and Leave operations +- **Java SDK**: Validates in Auth.checkClientId() method +- **Ruby SDK**: Validates in enter_with_presence_message() +- **.NET SDK**: Uses error constant UnableToEnterPresenceChannelNoClientId + +All SDKs throw error 91000 consistently when client ID is missing. + ## Prevention @@ -101,6 +139,7 @@ This is a client error that will not be automatically retried. You must configur - **Use meaningful identifiers**: User IDs, usernames, or session IDs work well - **Maintain consistency**: Use the same client ID across reconnections for the same user - **Validate before presence operations**: Check that client ID exists before calling presence methods +- **Include in token renewal**: Ensure client ID persists through token refreshes ## Security Considerations @@ -109,6 +148,7 @@ This is a client error that will not be automatically retried. You must configur - **Server-side validation**: Generate tokens server-side to ensure client ID authenticity - **Avoid sensitive data**: Don't use personal information as client IDs - **Unique identifiers**: Ensure each user has a unique client ID to prevent conflicts +- **Consistent assignment**: Server should control client ID assignment for security ## Related Resources @@ -116,7 +156,8 @@ This is a client error that will not be automatically retried. You must configur - [Ably Presence documentation](https://ably.com/docs/presence) - [Identified clients guide](https://ably.com/docs/auth/identified-clients) - [Token authentication](https://ably.com/docs/auth/token) -- Related errors: [91001](./91001-invalid-presence-state.md), [91003](./91003-presence-member-limit.md) +- [JWT authentication](https://ably.com/docs/auth/token#jwt) +- Related errors: [91001](./91001-invalid-presence-state.md), [91002](./91002-not-entered.md), [91003](./91003-presence-member-limit.md) ## Need Further Help? @@ -141,13 +182,13 @@ Our team will help you resolve this issue as quickly as possible. - Analysis File: https://github.com/ably/ably-os/blob/main/output/error-codes/research/91000-analysis.md - Knowledge File: https://github.com/ably/ably-os/blob/main/output/error-codes/research/91000-knowledge.md - Editorial Notes: https://github.com/ably/ably-os/blob/main/src/prompts/errors/editorial-notes.md - Specific note at line 121 about presence requiring client ID -- Existing Documentation: None found +- Existing Documentation: https://github.com/ably/docs/blob/main/src/pages/docs/platform/errors/codes/91000-presence-requires-client-id.mdx (enhanced version) - Repository Overviews: Not needed for this error --> + + + + + + + + + +# Error 91001: Presence operation failed due to invalid channel state + +## What Happened + +The presence operation could not be completed because the channel is not in a valid state to accept presence updates. + +## Quick Reference + +| Error Code | HTTP Status | Category | Retryable | +|------------|-------------|----------|-----------| +| 91001 | 400/500 | Channel State (Presence) | Yes - after channel reattachment | + +## Quick Fix + +- Ensure the channel is attached before entering presence +- Wait for the channel to reach the `attached` state +- Handle channel state transitions in your application + +## Error Messages + +You may see one of these messages: +- "unable to enter presence channel (invalid channel state)" +- "Unable to enter presence channel in detached or failed state" +- "unable to enter presence channel (incompatible channel state: [state])" +- "Unable to enter presence channel in [state] state" +- "Operation is not allowed when channel is in [state]" +- "Operation failed as channel transitioned to [state]" +- "Enter presence on suspended channel" + +## Common Causes + +1. **Channel not attached** (60% of cases) + + - Attempting presence operations before attaching to channel + - Channel has become detached due to network issues + - Channel failed during connection problems + +2. **Device wake/sleep cycles** (25% of cases) + + - Computer resumes after suspension (especially Windows) + - Mobile app returns from background + - Network transitions (WiFi to cellular) + +3. **Race conditions** (10% of cases) + + - Channel state changes during presence operation + - Multiple simultaneous operations on same channel + - Timing issues during connection recovery + +4. **Long-running connections** (5% of cases) + + - Extended disconnection causing channel suspension + - Connection state not properly managed + - Missing error recovery logic + +## Resolution Steps + +1. **Check channel state before presence operations** + ```javascript + // Ensure channel is attached before entering presence + if (channel.state === 'attached') { + await channel.presence.enter(); + } else { + // Wait for attachment + channel.once('attached', async () => { + await channel.presence.enter(); + }); + } + ``` + + +2. **Attach to the channel first** + ```javascript + // Proper sequencing: attach then enter presence + await channel.attach(); + await channel.presence.enter({ name: 'User Name' }); + ``` + + +3. **Handle channel state transitions** + ```javascript + channel.on('detached', () => { + console.log('Channel detached, presence operations will fail'); + // Attempt to reattach + channel.attach(); + }); + + channel.on('attached', () => { + console.log('Channel attached, presence operations now possible'); + // Re-enter presence if needed + channel.presence.enter(); + }); + ``` + + +4. **Implement recovery for device wake scenarios** + ```javascript + // Detect when device wakes from sleep + document.addEventListener('visibilitychange', () => { + if (!document.hidden) { + // Check connection and channel states + if (ably.connection.state !== 'connected') { + ably.connect(); + } + // Reattach channels and re-enter presence + channel.attach(() => { + channel.presence.enter(); + }); + } + }); + ``` + + +## Automatic Handling + +Ably SDKs do not automatically retry presence operations when this error occurs. Your application must: +- Monitor channel state +- Reattach to the channel when needed +- Retry presence operations after successful attachment + +Some SDKs queue presence operations during the `attaching` state, but will fail if the channel is `detached`, `failed`, or `suspended`. + + +## Prevention + +- Always verify channel state before presence operations +- Implement connection state monitoring +- Handle device sleep/wake events appropriately +- Use channel state event listeners to maintain presence +- Consider implementing automatic re-entry logic after reconnection + + +## Channel States Reference + +Presence operations are only allowed in the `attached` state: + +| State | Presence Allowed | Description | +|-------|------------------|-------------| +| `initialized` | No | Channel created but not connected | +| `attaching` | Queued | Operations queued until attached | +| `attached` | ✅ Yes | Only state allowing presence | +| `detaching` | No | Channel being removed | +| `detached` | No | Not connected to channel | +| `failed` | No | Channel in error state | +| `suspended` | No | Channel temporarily unavailable | + + + +## Related Resources + +- [Presence documentation](https://ably.com/docs/presence) +- [Channel state lifecycle](https://ably.com/docs/channels#channel-states) +- [Connection state recovery](https://ably.com/docs/connect/states) +- Related errors: [91000](https://help.ably.io/error/91000), [91004](https://help.ably.io/error/91004), [91005](https://help.ably.io/error/91005) + +## Need Further Help? + +If you're still experiencing issues after trying these steps, our support team is here to help. + +**Contact Ably Support**: https://ably.com/support + +When contacting support, please provide: +- Your account ID and app ID +- The full error message including error code 91001 +- Steps to reproduce the issue +- Any relevant code snippets (without sensitive credentials) +- The SDK and version you're using + +Our team will help you resolve this issue as quickly as possible. + + + + + + + + + + + + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/91004-presence-auto-reenter-failed.mdx b/src/pages/docs/platform/errors/codes/91004-presence-auto-reenter-failed.mdx new file mode 100644 index 0000000000..9dd2fcaf9c --- /dev/null +++ b/src/pages/docs/platform/errors/codes/91004-presence-auto-reenter-failed.mdx @@ -0,0 +1,224 @@ + + + + + + + + +# Error 91004: Presence auto-reenter failed + +## What Happened + +The SDK was unable to automatically re-enter your client into the presence set after reconnecting to the channel. + +## Quick Reference + +| Error Code | HTTP Status | Category | Retryable | +|------------|-------------|----------|-----------| +| 91004 | 400 | Presence Error (Channel) | No - requires manual intervention | + +## Quick Fix + +- Manually call `presence.enter()` to re-establish presence +- Check if your authentication has expired +- Verify your client still has presence permissions for the channel + +## Error Messages + +You may see one of these messages: +- "Presence auto re-enter failed" +- "Cannot automatically re-enter {clientId} on channel {channelName}" +- "unable to automatically re-enter presence channel for client_id '{clientId}'" +- "Re-entering member {memberKey} is failed" + +## Common Causes + +1. **Authentication expired during disconnection** (40% of cases) + - Token expired while disconnected + - Permissions changed during downtime + - Capability no longer includes presence rights + +2. **Channel state incompatibility** (30% of cases) + - Channel suspended after extended disconnection + - Presence member limit reached + - Channel closed and reopened with different parameters + +3. **Extended disconnection** (20% of cases) + - Connection recovery took too long + - Presence TTL expired + - Server cleared presence state + +4. **Permission changes** (10% of cases) + - Channel access revoked + - Presence capability removed + - Account or app suspended + +## Resolution Steps + +1. **Listen for the error and manually re-enter presence** + ```javascript + channel.on('update', (stateChange) => { + if (stateChange.reason?.code === 91004) { + // Manual re-entry required + channel.presence.enter((err) => { + if (err) { + console.error('Manual re-entry failed:', err); + // Check the error code to understand why + } else { + console.log('Successfully re-entered presence'); + } + }); + } + }); + ``` + + +2. **Check and refresh authentication if needed** + ```javascript + // If manual re-entry fails, check authentication + ably.auth.authorize((err, tokenDetails) => { + if (err) { + console.error('Auth refresh failed:', err); + return; + } + // Try presence.enter() again after auth refresh + channel.presence.enter(); + }); + ``` + + +3. **Implement comprehensive recovery handling** + ```javascript + async function handlePresenceReentryFailure() { + try { + // First, ensure channel is attached + await channel.attach(); + + // Then attempt to enter presence + await channel.presence.enter(); + console.log('Presence recovery successful'); + + } catch (err) { + console.error('Presence recovery failed:', err); + // Notify your application that presence is unavailable + } + } + ``` + + +4. **Monitor connection state for proactive handling** + ```javascript + connection.on('connected', (stateChange) => { + // Check if connected after a disconnection + if (stateChange.previous === 'disconnected' || + stateChange.previous === 'suspended') { + // Proactively verify presence state + channel.presence.get((err, members) => { + if (!members.find(m => m.clientId === myClientId)) { + // Not in presence, manually enter + channel.presence.enter(); + } + }); + } + }); + ``` + + +## Automatic Handling + +When a connection recovers after disconnection, Ably SDKs automatically attempt to re-enter presence for all channels where the client was previously present. Error 91004 indicates this automatic process failed. The SDK will: + +- Emit an 'update' event on the channel with this error +- Set the `resumed` flag to `true` in the state change +- Log the error at warning level or higher +- Continue normal channel operation (only presence is affected) + +The channel remains functional for publishing and subscribing to messages; only the presence state needs manual recovery. + + +## Prevention + +- **Implement token renewal before expiry**: Set up automatic token renewal to prevent authentication issues during disconnections +- **Handle presence errors proactively**: Listen for 'update' events with error codes to detect issues early +- **Store presence data locally**: Keep a local copy of presence data to facilitate recovery +- **Monitor connection stability**: Track disconnection patterns and implement appropriate recovery strategies + +## Related Resources + +- [Presence documentation](https://ably.com/docs/presence) +- [Connection state management](https://ably.com/docs/realtime/connection) +- [Authentication best practices](https://ably.com/docs/auth/token) +- Related errors: [91000](./91000-no-clientid-for-presence.mdx), [91001](./91001-invalid-channel-state.mdx) + +## Need Further Help? + +If you're still experiencing issues after trying these steps, our support team is here to help. + +**Contact Ably Support**: https://ably.com/support + +When contacting support, please provide: +- Your account ID and app ID +- The full error message including error code 91004 +- Steps to reproduce the issue +- Any relevant code snippets (without sensitive credentials) +- The SDK and version you're using + +Our team will help you resolve this issue as quickly as possible. + + + + + + + + + + + + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/91005-presence-state-out-of-sync.mdx b/src/pages/docs/platform/errors/codes/91005-presence-state-out-of-sync.mdx new file mode 100644 index 0000000000..279e530874 --- /dev/null +++ b/src/pages/docs/platform/errors/codes/91005-presence-state-out-of-sync.mdx @@ -0,0 +1,201 @@ + + + + + + + + +--- +error_code: 91005 +title: "Error 91005: Presence state is out of sync" +description: "The presence state for this channel has become desynchronized and cannot provide accurate member information" +--- + +# Error 91005: Presence state is out of sync + +## What Happened + +The presence state for this channel has lost synchronization with the server, meaning the list of members currently in the channel may be inaccurate or incomplete. + +## Quick Reference + +| Error Code | HTTP Status | Category | Retryable | +|------------|-------------|----------|-----------| +| 91005 | 400/500 | Channel Error (Presence) | Yes - automatic resync on reattachment | + +## Quick Fix + +- Allow the SDK to automatically resynchronize when the channel recovers +- Check the `syncComplete` flag before using presence data +- If immediate recovery needed, detach and reattach the channel + +## Error Messages + +You may see one of these messages: +- "Presence state is out of sync" +- "Presence state is out of sync due to connection interruption" +- "Presence state is out of sync due to the channel being in a SUSPENDED state" +- "Channel {name}: presence state is out of sync due to the channel being in a SUSPENDED state" + +## Common Causes + +1. **Channel suspension** (70% of cases) + - Channel entered SUSPENDED state during presence synchronization + - Typically occurs after 2+ minutes of disconnection + - Presence sync cannot complete while suspended + + +2. **Connection interruption during sync** (20% of cases) + - Network disconnection while presence was synchronizing + - Sync process interrupted before completion + - Partial presence data received + + +3. **Synchronization timeout** (10% of cases) + - Server took too long to send presence data + - High presence member count causing delays + - Network latency issues + + +## Resolution Steps + +1. **Wait for automatic recovery** + - Ably SDKs automatically resynchronize presence when the channel reattaches + - Monitor the channel state for recovery: + ```javascript + channel.on('attached', () => { + console.log('Channel reattached, presence will resynchronize'); + }); + ``` + + +2. **Check synchronization status** + - Verify presence is synchronized before using the data: + ```javascript + if (channel.presence.syncComplete) { + // Safe to use presence data + const members = await channel.presence.get(); + } else { + // Wait for sync to complete + channel.presence.once('sync', async () => { + const members = await channel.presence.get(); + }); + } + ``` + + +3. **Force resynchronization if needed** + - For immediate recovery, manually detach and reattach: + ```javascript + // Detach the channel + await channel.detach(); + + // Reattach to trigger fresh sync + await channel.attach(); + + // Wait for sync completion + channel.presence.once('sync', () => { + console.log('Presence resynchronized'); + }); + ``` + + +4. **Monitor channel state** + - Implement proper state handling: + ```javascript + channel.on('suspended', () => { + console.log('Channel suspended - presence may be out of sync'); + }); + + channel.on('attached', () => { + console.log('Channel attached - presence synchronizing'); + }); + ``` + + +## Automatic Handling + +Ably SDKs automatically handle presence resynchronization: +- When a channel moves from SUSPENDED to ATTACHED state, presence sync is automatically initiated +- The SDK discards the old presence state and fetches a fresh copy from the server +- No manual intervention required for standard recovery scenarios + +## Prevention + +- **Implement connection monitoring**: Track connection state to anticipate sync issues +- **Use the syncComplete flag**: Always check synchronization status before relying on presence data +- **Handle suspended state**: Implement appropriate UI feedback when channels are suspended +- **Consider caching**: Store last known good presence state for reference during sync issues + + +## Related Resources + +- [Presence documentation](https://ably.com/docs/presence) +- [Connection state management](https://ably.com/docs/realtime/connection) +- [Channel states explained](https://ably.com/docs/realtime/channels#states) +- Related errors: [91001 - Invalid channel state](./91001-invalid-channel-state.mdx), [91004 - Auto re-enter failed](./91004-auto-reenter-failed.mdx) + +## Need Further Help? + +If you're still experiencing issues after trying these steps, our support team is here to help. + +**Contact Ably Support**: https://ably.com/support + +When contacting support, please provide: +- Your account ID and app ID +- The full error message including error code 91005 +- Steps to reproduce the issue +- Any relevant code snippets (without sensitive credentials) +- The SDK and version you're using + +Our team will help you resolve this issue as quickly as possible. + + + + + + + + + + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/91100-member-implicitly-left-presence.mdx b/src/pages/docs/platform/errors/codes/91100-member-implicitly-left-presence.mdx new file mode 100644 index 0000000000..e6d462dc5d --- /dev/null +++ b/src/pages/docs/platform/errors/codes/91100-member-implicitly-left-presence.mdx @@ -0,0 +1,181 @@ + + + + + + + + +# Error 91100: Member implicitly left presence channel + +## What Happened + +A presence member was automatically removed from a channel when their connection ended unexpectedly or the system detected an inconsistent state. + +## Quick Reference + +| Error Code | HTTP Status | Category | Retryable | +|------------|-------------|----------|-----------| +| 91100 | 400 | Presence/Channel (Realtime) | No - indicates automatic cleanup | + +## Quick Fix + +- This is an informational error indicating automatic presence cleanup +- No action required - the system has already removed the member +- Update your UI to reflect the member's departure + +## Error Messages + +You may see one of these messages in presence leave events: +- "Member implicitly left presence channel (connection closed)" +- "Member implicitly left presence channel (no owners)" +- "Member implicitly left presence channel (every owning instance removed)" +- "Member implicitly left presence channel (unexpected owning instance)" + +## Common Causes + +1. **Unexpected disconnection** (80% of cases) + - Client lost network connection + - Application crashed or was terminated + - Browser tab or mobile app was closed + - Network timeout or failure + + +2. **Server maintenance or topology changes** (15% of cases) + - Frontend server deployment or restart + - Server instance migration + - Regional failover events + + +3. **Validation failures** (5% of cases) + - Presence set inconsistency detected + - Ownership validation failed + - Cross-region synchronization issues + + +## Resolution Steps + +1. **Understand this is automatic cleanup** + - Ably has already removed the member from presence + - No manual intervention needed + - The system is working as designed + + +2. **Handle in your presence subscriber** + ```javascript + channel.presence.subscribe('leave', (member) => { + if (member.reason?.code === 91100) { + // Member left unexpectedly (connection lost, crash, etc.) + console.log(`${member.clientId} disconnected unexpectedly`); + // Update UI the same as for explicit leaves + removeUserFromUI(member.clientId); + } + }); + ``` + + +3. **For debugging unexpected leaves** + - Check client-side connection stability + - Monitor for patterns of implicit leaves + - Review application lifecycle handling + - Ensure proper cleanup on app termination + + +## Automatic Handling + +Ably automatically: +- Detects when presence members lose connection +- Removes them from the presence set after timeout +- Broadcasts leave events with error code 91100 +- Maintains presence set consistency across regions + +No retry is needed or possible - the member has already been removed. + + +## Prevention + +To minimize implicit leaves: + +1. **Implement graceful shutdown** + ```javascript + // Clean leave on app termination + window.addEventListener('beforeunload', async () => { + await channel.presence.leave(); + }); + ``` + + +2. **Handle connection lifecycle properly** + - Monitor connection state changes + - Implement reconnection logic where appropriate + - Use presence heartbeats for critical applications + +3. **Design for implicit leaves** + - Treat implicit and explicit leaves identically in UI + - Don't show error messages to users for implicit leaves + - Consider it normal behavior in distributed systems + +## Related Resources + +- [Presence documentation](https://ably.com/docs/presence) +- [Connection state management](https://ably.com/docs/realtime/connection) +- [Presence best practices](https://ably.com/docs/best-practice#presence) +- Related errors: [91000](https://help.ably.io/error/91000), [91001](https://help.ably.io/error/91001), [91004](https://help.ably.io/error/91004), [91005](https://help.ably.io/error/91005) + +## Need Further Help? + +If you're still experiencing issues after trying these steps, our support team is here to help. + +**Contact Ably Support**: https://ably.com/support + +When contacting support, please provide: +- Your account ID and app ID +- The full error message including error code 91100 +- Steps to reproduce the issue +- Any relevant code snippets (without sensitive credentials) +- The SDK and version you're using + +Our team will help you resolve this issue as quickly as possible. + + + + + + + + + + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/92000-liveobjects-validation-error.mdx b/src/pages/docs/platform/errors/codes/92000-liveobjects-validation-error.mdx new file mode 100644 index 0000000000..b9bc359c4b --- /dev/null +++ b/src/pages/docs/platform/errors/codes/92000-liveobjects-validation-error.mdx @@ -0,0 +1,171 @@ + + + + + + + + +# Error 92000: LiveObjects validation error + +## What Happened + +A LiveObjects operation failed validation due to invalid data, missing state, or synchronization issues. + +## Quick Reference + +| Error Code | HTTP Status | Category | Retryable | +|------------|-------------|----------|-----------| +| 92000 | 500 | Server Error (LiveObjects) | No - requires fixing validation issue | + +## Quick Fix + +- Validate object IDs before operations +- Ensure objects exist before updates +- Handle state synchronization errors +- Consider resynchronizing LiveObjects state + +## Error Messages + +You may see one of these messages: +- "Invalid serial: {serial}" +- "Invalid site code: {siteCode}" +- "Missing object state; LiveCounter objectId={id}" +- "Missing object state; LiveMap objectId={id}" +- "Invalid object id string" + +## Common Causes + +1. **Invalid Object ID** (40% of cases) + + - Malformed object ID string + - Invalid format or characters + - Attempting to parse corrupted ID + +2. **Missing Object State** (30% of cases) + + - Object not yet synchronized + - State lost during disconnection + - Attempting operations on non-existent objects + +3. **Invalid Operation Sequencing** (20% of cases) + + - Invalid serial number in operation + - Invalid site code + - Out-of-order operations + +4. **Synchronization Issues** (10% of cases) + + - Network partitions causing state divergence + - Race conditions between concurrent operations + - State corruption during synchronization + +## Resolution Steps + +1. **Validate object IDs before operations** + + - Check ID format is valid + - Ensure ID exists in your system + - Verify ID hasn't been corrupted + +2. **Check object existence** + + - Verify the LiveObject exists before operations + - Wait for initial synchronization to complete + - Handle missing state gracefully + +3. **Implement error recovery** + + - Detect 92000 errors in catch blocks + - Clear local LiveObjects state + - Fetch fresh state from server + - Retry the operation after resynchronization + +4. **Monitor operation ordering** + + - Ensure operations have valid serial numbers + - Check site codes are correct + - Handle concurrent operations properly + +## Automatic Handling + +This error indicates a validation failure that cannot be automatically resolved. Your application must handle the error by fixing the validation issue or resynchronizing state. + +## Prevention + +- **Validate inputs**: Always validate object IDs and data before operations + +- **Handle disconnections**: Implement proper state recovery after connection loss +- **Use idempotent operations**: Design operations to be safely retryable +- **Monitor errors**: Track validation errors to identify patterns + +## Related Resources + +- [LiveObjects documentation](https://ably.com/docs/products/liveobjects) +- [Ably LiveObjects Product Page](https://ably.com/liveobjects) +- [Connection state management](https://ably.com/docs/realtime/connection) +- Related errors: Other 92xxx error codes for LiveObjects-specific issues + +## Need Further Help? + +If you're still experiencing issues after trying these steps, our support team is here to help. + +**Contact Ably Support**: https://ably.com/support + +When contacting support, please provide: +- Your account ID and app ID +- The full error message including error code 92000 +- Steps to reproduce the issue +- Any relevant code snippets (without sensitive credentials) +- The SDK and version you're using + +Our team will help you resolve this issue as quickly as possible. + + + + + + + + + + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/92001-conflicting-usage.mdx b/src/pages/docs/platform/errors/codes/92001-conflicting-usage.mdx new file mode 100644 index 0000000000..f0fd63bf17 --- /dev/null +++ b/src/pages/docs/platform/errors/codes/92001-conflicting-usage.mdx @@ -0,0 +1,205 @@ + + + + + + + + +# Error 92001: Conflicting Error Code Usage + +## What Happened + +This error code has two different meanings depending on which Ably feature you're using. You'll need to identify your scenario to find the correct resolution. + +## Quick Reference + +| Error Code | HTTP Status | Category | Retryable | +|------------|-------------|----------|-----------| +| 92001 | 400 | Cipher/Limits Error | No - requires configuration fix | + +## Quick Fix + +Determine which scenario applies to you: +- **Using Ruby SDK with encrypted channels?** Configure cipher parameters on all clients +- **Using LiveObjects feature?** Reduce objects on channel or upgrade your package limits +- **Unsure?** Check the full error message for context clues + +## Error Messages + +You may see one of these messages: + +**Ruby SDK (Channel Encryption)**: +- "Message cannot be decrypted as the channel is not set up for encryption & decryption" + +**LiveObjects Feature**: +- "Objects limit exceeded" + +## Common Causes + +### Scenario 1: Ruby SDK Channel Encryption (Most Common) + +1. **Missing cipher configuration** (80% of Ruby SDK cases) + - Receiving encrypted messages without cipher parameters + - Channel not configured for decryption + - Inconsistent encryption setup across clients + +2. **Configuration mismatch** (15% of Ruby SDK cases) + - Different cipher keys between clients + - Some clients encrypted, others not + - Updated encryption without updating all clients + +### Scenario 2: LiveObjects Limit Exceeded + +1. **Too many objects on channel** + - Exceeded account or application limits + - Objects not being cleaned up properly + - Accumulation of unused objects + +## Resolution Steps + +### For Ruby SDK Channel Encryption Issues + +1. **Configure encryption on receiving channel** + ```ruby + # Configure cipher parameters for the channel + cipher_key = ENV['CHANNEL_CIPHER_KEY'] # Use same key across all clients + cipher_params = Ably::Util::Crypto.get_default_params(key: cipher_key) + channel = client.channels.get('channel-name', cipher: cipher_params) + ``` + + +2. **Ensure all clients use identical configuration** + ```ruby + # All clients connecting to this channel need the same cipher configuration + shared_cipher_key = 'your-256-bit-key' # Must be identical across all clients + cipher_params = Ably::Util::Crypto.get_default_params(key: shared_cipher_key) + + # Apply to channel + encrypted_channel = ably.channels.get('secure-channel', cipher: cipher_params) + ``` + + +3. **Verify encryption is applied consistently** + - Check all publisher clients have encryption configured + - Ensure all subscriber clients have matching configuration + - Review any recent changes to encryption setup + +### For LiveObjects Limit Issues + +1. **Check current object count** + - Review the number of objects on the affected channel + - Identify unnecessary or obsolete objects + +2. **Clean up unused objects** + - Remove objects no longer needed + - Implement proper cleanup in your application logic + +3. **Upgrade your package if needed** + - Contact sales to increase object limits + - Review pricing plans for higher limits + - Consider distributing objects across multiple channels + +## Automatic Handling + +This error is not automatically retried by Ably SDKs as it indicates a configuration issue that must be resolved before the operation will succeed. + +## Prevention + +### For Channel Encryption +- Document encryption requirements for all channels +- Use environment variables for cipher keys +- Test encryption configuration before deploying +- Implement consistent key management across clients + + +### For LiveObjects +- Monitor object count regularly +- Implement automatic cleanup policies +- Design with limits in mind +- Use multiple channels to distribute load + +## Why This Conflict Exists + +This error code appears to have been assigned to different features at different times: +- The Ruby SDK has historically used 92001 for channel encryption errors +- LiveObjects documentation assigns 92001 to object limit errors + +We're working to resolve this conflict. In the meantime, use the error message and your application context to determine which scenario applies. + + +## Related Resources + +- [Channel Encryption Documentation](https://ably.com/docs/realtime/encryption) +- [LiveObjects Documentation](https://ably.com/docs/products/liveobjects) +- [Ruby SDK Reference](https://ably.com/docs/sdks/ruby) +- Related errors: [92002](./92002), [92003](./92003), [92004](./92004), [92005](./92005) (cipher errors in Ruby SDK) + +## Need Further Help? + +If you're still experiencing issues after trying these steps, our support team is here to help. + +**Contact Ably Support**: https://ably.com/support + +When contacting support, please provide: +- Your account ID and app ID +- The full error message including error code 92001 +- Which SDK and feature you're using (Ruby encryption or LiveObjects) +- Steps to reproduce the issue +- Any relevant code snippets (without sensitive credentials) +- The SDK and version you're using + +Our team will help you resolve this issue as quickly as possible. + + + + + + + + + + + + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/92002-cipher-algorithm-mismatch.mdx b/src/pages/docs/platform/errors/codes/92002-cipher-algorithm-mismatch.mdx new file mode 100644 index 0000000000..a92f9889c0 --- /dev/null +++ b/src/pages/docs/platform/errors/codes/92002-cipher-algorithm-mismatch.mdx @@ -0,0 +1,168 @@ + + + + + + + + +# Error 92002: Cipher algorithm mismatch + +## What Happened + +The encryption algorithm used to encrypt a message doesn't match the algorithm configured for decryption on this channel. + +## Quick Reference + +| Error Code | HTTP Status | Category | Retryable | +|------------|-------------|----------|-----------| +| 92002 | 400 | Cipher/Encryption Error | No - requires configuration fix | + +## Quick Fix + +- Ensure all clients on the channel use the same cipher algorithm +- Verify both sender and receiver use matching encryption settings +- Check that development and production environments use consistent algorithms + +## Error Messages + +You may see this message: +- "Cipher algorithm {channel_algorithm} does not match message cipher algorithm of {message_algorithm}" + +The placeholders show the actual algorithms in conflict (e.g., AES-128-CBC vs AES-256-CBC). + +## Common Causes + +1. **Different algorithm configurations** (80% of cases) + - One client using AES-128-CBC, another using AES-256-CBC + - Algorithm changed without updating all clients + - Development vs production environment mismatch + +2. **Algorithm migration in progress** (15% of cases) + - Upgrading encryption strength without coordinating all clients + - Partial deployment of algorithm changes + +3. **Legacy client compatibility** (5% of cases) + - Older SDK versions using different default algorithms + - Mixed SDK versions in the same channel + +## Resolution Steps + +1. **Identify the algorithm mismatch** + - Check the error message for the specific algorithms in conflict + - The channel algorithm is what your current client is configured to use + - The message algorithm is what was used to encrypt the received message + + +2. **Align all clients to use the same algorithm** + - Choose a standard algorithm for all clients (recommend AES-256-CBC for better security) + - Update cipher configuration across all applications + + +3. **Update your cipher configuration** + - Ensure consistent cipher params across all clients + - See [Ably encryption documentation](https://ably.com/docs/realtime/encryption) for configuration details + + +4. **For algorithm migration** + - Deploy receivers that can handle both algorithms temporarily + - Update all senders to the new algorithm + - Remove support for the old algorithm once migration is complete + + +## Automatic Handling + +This is a configuration error that will not be automatically retried. The cipher algorithm mismatch must be resolved before messages can be successfully decrypted. + +## Prevention + +- **Standardize on one algorithm**: Use AES-256-CBC for all clients for maximum security +- **Document your choice**: Keep encryption configuration documented and versioned +- **Test compatibility**: Verify encryption works across all client types before deployment +- **Monitor for mismatches**: Set up alerts for cipher-related errors + + +## Related Resources + +- [Ably encryption documentation](https://ably.com/docs/realtime/encryption) +- [Cipher params configuration](https://ably.com/docs/realtime/encryption#cipher-params) +- Related errors: [92001](./92001-channel-not-configured-for-encryption.md), [92003](./92003-decryption-failure.md), [92004](./92004-unsupported-cipher-algorithm.md) + +## Need Further Help? + +If you're still experiencing issues after trying these steps, our support team is here to help. + +**Contact Ably Support**: https://ably.com/support + +When contacting support, please provide: +- Your account ID and app ID +- The full error message including error code 92002 +- Steps to reproduce the issue +- Any relevant code snippets (without sensitive credentials) +- The SDK and version you're using + +Our team will help you resolve this issue as quickly as possible. + + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/92003-cipher-decryption-failed.mdx b/src/pages/docs/platform/errors/codes/92003-cipher-decryption-failed.mdx new file mode 100644 index 0000000000..e29747d895 --- /dev/null +++ b/src/pages/docs/platform/errors/codes/92003-cipher-decryption-failed.mdx @@ -0,0 +1,161 @@ + + + + + + + + +# Error 92003: Cipher decryption failed + +## What Happened + +The SDK was unable to decrypt an encrypted message, typically because the decryption key doesn't match the key used for encryption. + +## Quick Reference + +| Error Code | HTTP Status | Category | Retryable | +|------------|-------------|----------|-----------| +| 92003 | 400 | Cipher/Encryption Error | No - requires correct encryption key | + +## Quick Fix + +- Verify you're using the correct encryption key for this channel +- Ensure the key format matches (base64, hex, or raw) +- Check that both publisher and subscriber use identical cipher parameters + +## Error Messages + +You may see one of these messages: +- "CipherError decrypting data, the private key may not be correct" +- OpenSSL cipher errors indicating decryption failure + +## Common Causes + +1. **Incorrect encryption key** (80% of cases) + - Using wrong environment's key (dev vs production) + - Key mismatch between publisher and subscriber + - Copy-paste errors when configuring keys + +2. **Key encoding issues** (15% of cases) + - Base64 vs hex vs raw format confusion + - Key truncation during configuration + - Character encoding problems + +3. **Key rotation without coordination** (5% of cases) + - Publisher updated to new key + - Subscriber still using old key + - Messages encrypted with different keys in same channel + +## Resolution Steps + +1. **Verify the encryption key** + + - Check you're using the correct key for your environment + - Ensure the key hasn't been truncated or modified + - Confirm both publisher and subscriber have the same key + +2. **Check key encoding and format** + + - Verify if key should be base64, hex, or raw bytes + - Ensure consistent encoding across all clients + - Check for any character set conversion issues + +3. **Review cipher parameters configuration** + + - Confirm algorithm matches between encryption and decryption + - Verify initialization vector (IV) handling if custom + - Check cipher mode (CBC, GCM, etc.) consistency + +4. **Test with known good configuration** + - Try decrypting a test message with known parameters + - Use Ably's default cipher params as baseline + - Isolate whether issue is with specific messages or all encrypted data + +## Automatic Handling + +This is a configuration error that SDKs cannot automatically resolve. The application must provide the correct encryption key and parameters. + +## Prevention + +- Store encryption keys securely using vault or KMS services +- Implement key versioning for smooth rotation +- Test encryption/decryption in staging before production +- Monitor decryption failures for security alerts +- Document key distribution and rotation procedures + +## Related Resources + +- [Encryption documentation](https://ably.com/docs/realtime/encryption) +- [Cipher parameters guide](https://ably.com/docs/realtime/encryption#cipher-params) +- Related errors: 92002 (cipher algorithm mismatch) + +## Need Further Help? + +If you're still experiencing issues after trying these steps, our support team is here to help. + +**Contact Ably Support**: https://ably.com/support + +When contacting support, please provide: +- Your account ID and app ID +- The full error message including error code 92003 +- Steps to reproduce the issue +- Any relevant code snippets (without sensitive credentials) +- The SDK and version you're using + +Our team will help you resolve this issue as quickly as possible. + + + + + + + + + + + + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/92004-dual-purpose-cipher-or-object-error.mdx b/src/pages/docs/platform/errors/codes/92004-dual-purpose-cipher-or-object-error.mdx new file mode 100644 index 0000000000..cfa4a8be5c --- /dev/null +++ b/src/pages/docs/platform/errors/codes/92004-dual-purpose-cipher-or-object-error.mdx @@ -0,0 +1,222 @@ + + + + + + + + +# Error 92004: Dual Purpose - Cipher Algorithm or Object Not Found + +## What Happened + +This error has two completely different meanings depending on your context: +1. **Ruby SDK**: An unsupported cipher algorithm was specified for encryption +2. **LiveObjects**: An attempt was made to access an object that doesn't exist + +## Quick Reference + +| Error Code | HTTP Status | Category | Retryable | +|------------|-------------|----------|-----------| +| 92004 | 400 (Ruby SDK) or 404 (LiveObjects) | Cipher Error or Object Not Found | No - requires configuration fix | + +## Quick Fix + +**If you're using encryption (Ruby SDK)**: +- Switch to a supported algorithm: AES-128-CBC or AES-256-CBC +- Use the SDK's default encryption settings +- Check for typos in algorithm names + +**If you're using LiveObjects**: +- Verify the object ID exists before accessing +- Listen for object lifecycle events +- Handle deletion scenarios gracefully + +## Error Messages + +You may see one of these messages: +- "unsupported cipher algorithm" (Ruby SDK) +- "unable to fetch objects tree for not found object: [object-id]" (LiveObjects) +- Dynamic error message from encryption library (Ruby SDK) + +## Common Causes + +### For Ruby SDK Encryption + +1. **Unsupported algorithm specified** (90% of cases) + - Using DES, 3DES, or other deprecated algorithms + - Custom or proprietary algorithms + - Misspelled algorithm names (e.g., 'aes256cbc' instead of 'aes-256-cbc') + + +2. **Platform-specific algorithm names** (10% of cases) + - Using algorithm names from other libraries + - Case sensitivity issues + + +### For LiveObjects + +1. **Accessing deleted objects** (60% of cases) + - Object was deleted by another client + - Attempting operations on stale object references + + +2. **Invalid object ID** (40% of cases) + - Typo in object identifier + - Using ID from different channel or app + + +## Resolution Steps + +### If Using Ruby SDK Encryption + +1. **Use a supported algorithm** + ```ruby + # Explicitly use AES-256-CBC (recommended) + cipher_params = Ably::Util::Crypto.get_default_params( + key: your_encryption_key, + algorithm: 'aes-256-cbc' + ) + + # Or use AES-128-CBC + cipher_params = Ably::Util::Crypto.get_default_params( + key: your_encryption_key, + algorithm: 'aes-128-cbc' + ) + ``` + + +2. **Use SDK defaults (simplest approach)** + ```ruby + # Let the SDK choose the default algorithm (AES-256-CBC) + cipher_params = Ably::Util::Crypto.get_default_params(key: your_encryption_key) + ``` + + +3. **Verify algorithm spelling and format** + - Must use hyphens: 'aes-256-cbc' not 'aes256cbc' + - Case-insensitive in Ruby SDK + - Avoid spaces or underscores + +### If Using LiveObjects + +1. **Implement object lifecycle handling** + ```javascript + // Listen for object deletion events + liveMap.subscribe('deleted', () => { + console.log('Object was deleted'); + // Clean up references and UI + }); + ``` + + +2. **Check object existence before operations** + ```javascript + try { + const object = await channel.liveObjects.get(objectId); + // Proceed with operations + } catch (error) { + if (error.code === 92004) { + console.log('Object does not exist'); + // Handle missing object scenario + } + } + ``` + +3. **Retry with valid object ID** + - Verify the object ID format + - Ensure you're using the correct channel + - Check if object was created successfully + +## Automatic Handling + +This error is not automatically retried by Ably SDKs as it indicates a configuration or state issue that must be resolved by your application. + +## Prevention + +### For Encryption (Ruby SDK) +- Always use SDK-provided encryption constants +- Document your encryption requirements +- Test algorithm support on all target platforms +- Prefer SDK defaults when possible + + +### For LiveObjects +- Implement proper lifecycle event handling +- Maintain object reference validity +- Handle concurrent deletion scenarios +- Use optimistic locking patterns where appropriate + +## Related Resources + +- [Ably Encryption Documentation](https://ably.com/docs/realtime/encryption) +- [LiveObjects Documentation](https://ably.com/docs/products/liveobjects) +- [Ruby SDK Crypto Reference](https://github.com/ably/ably-ruby#encryption) +- Related errors: [92001](./92001-invalid-encrypted-data.md), [92003](./92003-decryption-error.md), [92005](./92005-invalid-cipher-params.md) + +## Need Further Help? + +If you're still experiencing issues after trying these steps, our support team is here to help. + +**Contact Ably Support**: https://ably.com/support + +When contacting support, please provide: +- Your account ID and app ID +- The full error message including error code 92004 +- Steps to reproduce the issue +- Any relevant code snippets (without sensitive credentials) +- The SDK and version you're using + +Our team will help you resolve this issue as quickly as possible. + + + + + + + + + + + + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/92005-duplicate-context-error.mdx b/src/pages/docs/platform/errors/codes/92005-duplicate-context-error.mdx new file mode 100644 index 0000000000..fea4b7bda6 --- /dev/null +++ b/src/pages/docs/platform/errors/codes/92005-duplicate-context-error.mdx @@ -0,0 +1,217 @@ + + + + + + + + +# Error 92005: Duplicate context error - cipher or LiveObjects path issue + +## What Happened + +This error code is currently used in two different contexts within Ably's systems. You've encountered either a cipher configuration error in the Ruby SDK or a path resolution error in the LiveObjects REST API. + +## Quick Reference + +| Error Code | HTTP Status | Category | Retryable | +|------------|-------------|----------|-----------| +| 92005 | 400 (REST API) or N/A (SDK) | Cipher Error (Ruby SDK) or LiveObjects Error (REST API) | No - requires configuration fix | + +## Quick Fix + +Identify which context applies to you: +- **Using Ruby SDK encryption?** Check your cipher key format and message data +- **Using LiveObjects REST API?** Verify the object path exists before updating +- **Unsure?** Check the error message for clues about encryption or paths + +## Error Messages + +You may see one of these messages: + +**Ruby SDK (Cipher context):** +- Various ArgumentError messages related to encryption parameters +- Key length or format validation errors +- Invalid message data type errors + +**LiveObjects REST API context:** +- "No objects found matching operation path" +- "no objects matched path: [your.path.here]" + +## Common Causes + +### If Using Ruby SDK Encryption + +1. **Invalid cipher key format** (60% of cases) + + - Base64 decoding failures + - Wrong key length for the algorithm (e.g., not 32 bytes for AES-256) + - Malformed or corrupted key data + +2. **Invalid message data** (30% of cases) + + - Non-serializable data types + - Encoding conflicts + - Binary data handling issues + +3. **Initialization vector problems** (10% of cases) + + - Malformed IV + - IV length mismatch + +### If Using LiveObjects REST API + +1. **Path doesn't exist** (90% of cases) + + - Attempting to update a non-existent nested element + - Typo in the path specification + - Object was deleted before the update + +2. **Incorrect path syntax** (10% of cases) + + - Malformed path structure + - Missing path separators + +## Resolution Steps + +### For Ruby SDK Cipher Errors + +1. **Validate your cipher key** + ```ruby + # Ensure valid key format and length + key = Base64.decode64(ENV['CIPHER_KEY_BASE64']) + raise "Invalid key length" unless key.bytesize == 32 # For AES-256 + + cipher_params = Ably::Util::Crypto.get_default_params(key: key) + ``` + + +2. **Check your message data format** + ```ruby + # Ensure message data is valid + message = { + name: 'event', + data: 'string or hash' # Must be serializable + } + ``` + + +3. **Test with simple data first** + - Start with a plain string message + - Gradually add complexity + - Verify encoding consistency (use UTF-8) + + +### For LiveObjects REST API Errors + +1. **Verify the object exists before updating** + - First retrieve the object to confirm it exists + - Check the exact path structure matches your data + + +2. **Create the object path if it doesn't exist** + - Use appropriate creation operations before attempting updates + - Build nested structures step by step + + +3. **Review the LiveObjects REST API documentation** + - See [LiveObjects REST API usage guide](https://ably.com/docs/liveobjects/rest-api-usage#updating-objects-by-path) + - Pay attention to path syntax requirements + + +## Automatic Handling + +This is a client error that will not be automatically retried. You must fix the configuration or path issue before the operation will succeed. + +## Prevention + +### For Ruby SDK Users +- Validate cipher parameters before initializing channels +- Use consistent encoding throughout your application +- Test encryption setup with known-good test data +- Log cipher configuration details (never log keys!) for debugging + + +### For LiveObjects Users +- Always check object existence before updates +- Use creation operations for new paths +- Implement proper error handling for path operations + + +## Related Resources + +- [Ably Encryption Documentation](https://ably.com/docs/realtime/encryption) +- [LiveObjects REST API Documentation](https://ably.com/docs/liveobjects/rest-api-usage) +- [Ruby SDK Cipher Implementation](https://github.com/ably/ably-ruby/blob/main/lib/ably/models/message_encoders/cipher.rb) +- Related cipher errors: 92003 (decryption error), 92004 (unsupported algorithm) + +## Need Further Help? + +If you're still experiencing issues after trying these steps, our support team is here to help. + +**Contact Ably Support**: https://ably.com/support + +When contacting support, please provide: +- Your account ID and app ID +- The full error message including error code 92005 +- Steps to reproduce the issue +- Any relevant code snippets (without sensitive credentials) +- The SDK and version you're using + +Our team will help you resolve this issue as quickly as possible. + + + + + + + + + + + + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/92100-encoding-value-too-long.mdx b/src/pages/docs/platform/errors/codes/92100-encoding-value-too-long.mdx new file mode 100644 index 0000000000..1fad0ad3fb --- /dev/null +++ b/src/pages/docs/platform/errors/codes/92100-encoding-value-too-long.mdx @@ -0,0 +1,178 @@ + + + + + + + + +# Error 92100: Encoding value too long + +## What Happened + +The message encoding metadata string exceeded the maximum allowed length of 512 characters. + +## Quick Reference + +| Error Code | HTTP Status | Category | Retryable | +|------------|-------------|----------|-----------| +| 92100 | 400 | Client Error (Encoding) | No - requires fixing message encoding | + +## Quick Fix + +- Reduce the number of encoding transformations applied to your message +- Avoid encoding already-encoded data +- Use only essential encoding steps for your use case + +## Error Messages + +You may see this message: +- "Encoding error, encoding value is too long: '{encoding}'" + +The `{encoding}` shows the actual encoding string that exceeded the limit. + +## Common Causes + +1. **Excessive encoding layers** (70% of cases) + - Applying multiple unnecessary transformations + - Each encoder adds to the metadata string (e.g., `json/utf-8/base64/cipher+aes-256-cbc/gzip`) + + +2. **Recursive encoding** (20% of cases) + - Encoding already-encoded messages + - Double-encoding JSON data + - Processing the same message through encoders multiple times + + +3. **Unnecessary transformations** (10% of cases) + - Including redundant base64 encoding + - Multiple compression layers + - Using both encryption and encoding when only one is needed + + +## Resolution Steps + +1. **Review your encoding chain** + - Check which encodings are being applied to your messages + - The encoding string concatenates all transformations with '/' separator + - Example problematic chain: `json/utf-8/base64/cipher+aes-256-cbc/gzip/base64` + + +2. **Reduce encoding layers** + - Use only the essential encodings for your use case + - Avoid encoding data that's already in the correct format + - Choose either compression or encryption, not necessarily both + + +3. **Optimize your message structure** + - Apply compression before encryption if using both + - Use efficient serialization formats + - Consider sending raw data when appropriate + + +4. **Monitor encoding chain length** + - Keep track of the encoding metadata string length + - Remember the 512 character limit includes all transformation identifiers + - Test with production-like data to catch issues early + + +## Automatic Handling + +This is a client-side validation error that occurs before the message is sent to Ably servers. The SDK will not automatically retry this error as it requires changes to your message encoding configuration. + + +## Prevention + +- Use minimal necessary encodings for your messages +- Avoid double-encoding data (e.g., JSON-encoding already-JSON data) +- Choose the most efficient transformation order +- Document your encoding requirements to prevent unnecessary additions +- Regularly review and optimize your encoding pipeline + + +## Performance Impact + +Long encoding chains impact your application by: +- Slowing message processing +- Increasing message size and bandwidth usage +- Adding latency to publish and subscribe operations +- Consuming more CPU for encoding/decoding + + +## Related Resources + +- [Message encoding documentation](https://ably.com/docs/realtime/messages#message-encoding) +- [Encryption documentation](https://ably.com/docs/realtime/encryption) +- Related errors: [92001](./92001-encoding-error.md), [92005](./92005-decoding-error.md) + +## Need Further Help? + +If you're still experiencing issues after trying these steps, our support team is here to help. + +**Contact Ably Support**: https://ably.com/support + +When contacting support, please provide: +- Your account ID and app ID +- The full error message including error code 92100 +- Steps to reproduce the issue +- Any relevant code snippets (without sensitive credentials) +- The SDK and version you're using + +Our team will help you resolve this issue as quickly as possible. + + + + + + + + + + + + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/93001-annotations-channel-state-invalid.mdx b/src/pages/docs/platform/errors/codes/93001-annotations-channel-state-invalid.mdx new file mode 100644 index 0000000000..7966972f99 --- /dev/null +++ b/src/pages/docs/platform/errors/codes/93001-annotations-channel-state-invalid.mdx @@ -0,0 +1,219 @@ + + + + + + + + +# Error 93001: Annotations channel state invalid + +## What Happened + +The channel is not in the correct state to perform annotations operations. The channel must be attached before you can use annotations features. + +## Quick Reference + +| Error Code | HTTP Status | Category | Retryable | +|------------|-------------|----------|-----------| +| 93001 | 400 | Client Error (Annotations) | No - requires channel attachment | + +## Quick Fix + +- Ensure the channel is attached before using annotations +- Wait for the 'attached' event if currently attaching +- Check channel state before annotations operations + +## Error Messages + +You'll see this message: +- "Annotations channel state invalid for operation" + +## Common Causes + +1. **Channel not attached** (Most common) + - Attempting annotations operations immediately after getting channel reference + - Channel is still in 'initialized' or 'attaching' state + - Not waiting for attachment to complete + +2. **Channel in error state** + - Channel is in 'suspended', 'failed', or 'detached' state + - Previous connection error not resolved + - Channel attachment failed + +3. **Premature operation** + - Race condition between attachment and annotations operation + - Not using proper event handlers for state transitions + +## Resolution Steps + +1. **Ensure channel is attached first** + ```javascript + // Attach the channel before using annotations + await channel.attach(); + + // Now annotations operations are safe + channel.annotations.subscribe((annotation) => { + console.log('Annotation received:', annotation); + }); + ``` + + +2. **Check channel state before operations** + ```javascript + if (channel.state === 'attached') { + // Safe to use annotations + channel.annotations.subscribe(); + } else { + // Wait for attachment + channel.once('attached', () => { + channel.annotations.subscribe(); + }); + } + ``` + + +3. **Handle attachment with callbacks** + ```javascript + channel.attach((err) => { + if (err) { + console.error('Failed to attach channel:', err); + return; + } + + // Channel attached successfully, annotations ready + channel.annotations.subscribe(); + }); + ``` + + +4. **Monitor channel state changes** + ```javascript + channel.on('attached', () => { + console.log('Channel attached - annotations available'); + }); + + channel.on('detached', () => { + console.log('Channel detached - annotations unavailable'); + }); + ``` + +## Automatic Handling + +Ably SDKs do not automatically retry annotations operations. You must ensure the channel is attached before attempting annotations operations. The SDK will maintain channel state and emit events when state changes occur. + +## Prevention + +- Always attach channels before using extended features like annotations +- Implement proper state checking in your initialization code +- Use async/await or callbacks to ensure sequential operations +- Monitor channel state events to handle disconnections gracefully +- Consider implementing a wrapper that ensures attachment before operations + +## Code Examples + +### Proper Annotations Setup +```javascript +// Initialize Ably client +const ably = new Ably.Realtime({ key: 'your-api-key' }); + +// Get channel reference +const channel = ably.channels.get('my-channel'); + +// Ensure channel is attached before using annotations +async function setupAnnotations() { + try { + // Wait for channel attachment + await channel.attach(); + console.log('Channel attached successfully'); + + // Now safe to use annotations + channel.annotations.subscribe((annotation) => { + console.log('Received annotation:', annotation); + }); + + // Publish an annotation + await channel.annotations.publish({ + type: 'comment', + text: 'This is an annotation' + }); + + } catch (error) { + console.error('Failed to setup annotations:', error); + } +} + +setupAnnotations(); +``` + + +## Related Resources + +- [Channel state documentation](https://ably.com/docs/realtime/channels#channel-states) +- [Channel lifecycle events](https://ably.com/docs/realtime/channels#channel-lifecycle) +- Related errors: [91004](https://help.ably.io/error/91004) (Presence state error) + +## Need Further Help? + +This error code has limited documentation available. If you encounter this error, please contact Ably support at https://ably.com/support with: +- The full error message including error code 93001 +- What action triggered the error +- Your account ID and app ID +- The SDK and version you're using +- Any relevant code snippets (without sensitive credentials) + +Our support team will help you resolve this issue as quickly as possible. + + + + + + + + + + + + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/93002-mutable-messages-feature-required.mdx b/src/pages/docs/platform/errors/codes/93002-mutable-messages-feature-required.mdx new file mode 100644 index 0000000000..b0cbd67a66 --- /dev/null +++ b/src/pages/docs/platform/errors/codes/93002-mutable-messages-feature-required.mdx @@ -0,0 +1,162 @@ + + + + + + + + +# Error 93002: Mutable Messages feature required + +## What Happened + +The operation you're attempting requires the Mutable Messages feature to be enabled, but it's not currently available on this channel. + +## Quick Reference + +| Error Code | HTTP Status | Category | Retryable | +|------------|-------------|----------|-----------| +| 93002 | 400 | Channel Error (Feature Gate) | No - requires feature enablement | + +## Quick Fix + +- Verify the Mutable Messages feature is enabled for your account +- Check you're using the correct app with the feature enabled +- Contact Ably support to enable this feature if needed + +## Error Messages + +You may see one of these messages: +- "Annotation-subscribe mode is only supported on channels with Mutable Messages enabled in channel namespace settings" +- "Can only publish annotations to channels in a namespace with the Mutable Messages feature enabled" + +## Common Causes + +1. **Feature not enabled** (80% of cases) + - Mutable Messages feature not activated for your account + - Using an app that doesn't have the feature enabled + - Feature not configured for the specific namespace + +2. **Using annotation operations** (15% of cases) + - Attempting to subscribe to message annotations + - Publishing messages with annotations + - Using message editing capabilities + +3. **Wrong environment** (5% of cases) + - Development environment has feature, production doesn't + - Using incorrect app credentials + +## Resolution Steps + +1. **Verify feature availability** + - Check your Ably dashboard for available features + - Confirm your account plan includes Mutable Messages + - Verify which apps have the feature enabled + + +2. **Enable the feature** + - Contact Ably support at https://ably.com/support + - Specify which apps need the Mutable Messages feature + - Provide your account ID and use case requirements + + +3. **Use the correct app** + - Ensure you're using API keys from an app with the feature enabled + - Double-check environment variables and configuration + - Test the connection with a simple annotation operation + +4. **Alternative approaches if feature unavailable** + - Use separate channels for metadata instead of annotations + - Implement application-level annotation logic + - Store annotations in an external database + - Use standard message metadata fields for additional data + + +## Automatic Handling + +This is a feature availability error that will not be automatically retried. The Mutable Messages feature must be enabled at the account level before operations requiring it will succeed. + +## Prevention + +- Document which features your application requires +- Test feature availability in development environments first +- Plan for graceful degradation if the feature is unavailable +- Consider fallback strategies for environments without the feature + + +## Related Resources + +- [Ably Support](https://ably.com/support) - Contact for feature enablement +- [Ably Dashboard](https://ably.com/dashboard) - Check your account features +- [Ably Pricing](https://ably.com/pricing) - View plan features + +## Need Further Help? + +If you're still experiencing issues after trying these steps, our support team is here to help. + +**Contact Ably Support**: https://ably.com/support + +When contacting support, please provide: +- Your account ID and app ID +- The full error message including error code 93002 +- Steps to reproduce the issue +- Any relevant code snippets (without sensitive credentials) +- The SDK and version you're using + +Our team will help you resolve this issue as quickly as possible. + + + + + + + + + + + + + + \ No newline at end of file From 6b079d81bfce9ab01aff61cbdaca36f8ee321d04 Mon Sep 17 00:00:00 2001 From: Matthew O'Riordan Date: Fri, 22 Aug 2025 14:45:29 +0100 Subject: [PATCH 3/6] Improve doc prompts See improvements https://github.com/ably/ably-os/pull/3/commits/8ca41acd3d2e84d64edc1a7d2468729cebaf8f43 Only applied on a small sample of errors --- .../errors/codes/40000-bad-request.mdx | 150 ++++++----- .../codes/40001-invalid-request-body.mdx | 152 +++++++---- .../errors/codes/40400-resource-not-found.mdx | 241 +++++++++-------- .../codes/50000-internal-server-error.mdx | 250 +++++++++++++----- 4 files changed, 497 insertions(+), 296 deletions(-) diff --git a/src/pages/docs/platform/errors/codes/40000-bad-request.mdx b/src/pages/docs/platform/errors/codes/40000-bad-request.mdx index 8457ed9cbb..d687c29d6e 100644 --- a/src/pages/docs/platform/errors/codes/40000-bad-request.mdx +++ b/src/pages/docs/platform/errors/codes/40000-bad-request.mdx @@ -1,20 +1,20 @@ - + - + # Error 40000: Bad request ## What Happened -Your request cannot be processed because it doesn't meet Ably's requirements - this could be due to invalid parameters, wrong connection state, missing prerequisites, or protocol violations. +Your request cannot be processed because it doesn't meet Ably's requirements. This could be due to invalid parameters, wrong connection state, missing prerequisites, or protocol violations. ## Quick Reference @@ -33,7 +33,7 @@ Your request cannot be processed because it doesn't meet Ably's requirements - t You may see one of these messages: - + - "Unable to publish in Suspended state" - Connection suspended after 2+ minutes disconnected - "Message cannot be published. Client is not allowed to queue messages when connection is in Initialized state" - Message queueing is disabled - "Channel is not attached" - Channel must be attached before operations @@ -44,66 +44,71 @@ You may see one of these messages: - "options.modes must be an array" - Invalid channel modes format - "room already exists with different options" - Room configuration conflict - "cannot subscribe to occupancy; occupancy events are not enabled in room options" - Feature not enabled +- "invalid Timeserial {value}, missing @ character" - Malformed timeserial format +- "invalid Timeserial {value}, missing - character" - Malformed timeserial format - + ## Common Causes -### 1. Input Validation Errors (40% of cases) +### 1. Parameter Validation Errors (40% of cases) - **Wrong data types**: Providing string when object expected, or vice versa - **Format violations**: Invalid timeserials, channel names, or client IDs - **Missing required fields**: Required parameters not provided - **Values out of range**: Message size exceeded, recipient count over limit - + -### 2. State Prerequisites Not Met (30% of cases) +### 2. State Prerequisites Not Met (35% of cases) - **Publishing in suspended state**: Connection has been disconnected for over 2 minutes - **Channel not attached**: Attempting operations before channel attachment - **Connection not established**: Operations attempted before connection is ready - **Message queueing disabled**: `queueMessages: false` prevents automatic queueing - **Component lifecycle violations**: Operations on unmounted or disposed components - - + + -### 3. Resource Conflicts (15% of cases) -- **Duplicate resources**: Attempting to create already existing resources -- **Configuration conflicts**: Getting room with different options than originally specified -- **Immutable modifications**: Trying to change channel options after creation +### 3. Feature Not Enabled (15% of cases) +- **Presence operations**: Attempting presence without enabling in room options +- **Occupancy tracking**: Using occupancy features without enabling them +- **Typing indicators**: Starting typing without enabling the feature +- **Reactions**: Using reactions without enabling in room configuration - + -### 4. Protocol and Serialization Issues (10% of cases) +### 4. Protocol and Serialization Issues (5% of cases) - **.NET SDK serialization**: Custom serializers sending enums as strings instead of integers - **WebSocket message format**: Protocol messages improperly formatted - **Batch format errors**: JSON sent instead of msgpack for batch operations +- **Timeserial parsing**: Missing separators or non-numeric components - + -### 5. Feature Not Enabled (5% of cases) -- **Presence operations**: Attempting presence without enabling in room options -- **Occupancy tracking**: Using occupancy features without enabling them -- **Typing indicators**: Starting typing without enabling the feature +### 5. Resource Conflicts (5% of cases) +- **Duplicate resources**: Attempting to create already existing resources +- **Configuration conflicts**: Getting room with different options than originally specified +- **Immutable modifications**: Trying to change channel options after creation +- **Transport superseded**: Newer connection has replaced the current transport - + ## Resolution Steps ### 1. For State-Related Errors **If you see "Unable to publish in Suspended state":** - + 1. The connection has been disconnected for over 2 minutes and entered suspended state 2. Create a new connection or wait for automatic recovery 3. Monitor connection state to prevent future suspensions 4. See [Connection state management documentation](https://ably.com/docs/realtime/connection#connection-state-recovery) **If you see "Message cannot be published" with connection state errors:** - + 1. Check if `queueMessages` is set to `false` in your client options 2. If so, either: - - Enable message queueing (recommended): `new Ably.Realtime({ key: 'key', queueMessages: true })` + - Enable message queueing (recommended): Set `queueMessages: true` in client options - Or wait for connection before publishing (only if queueing must be disabled) 3. With default settings, messages are automatically queued - this error indicates a configuration issue @@ -111,7 +116,7 @@ You may see one of these messages: 1. With default settings, messages are automatically queued - this error indicates a configuration issue 2. If you've disabled queueing (`queueMessages: false`), wait for attachment before operations 3. Review [Channel lifecycle documentation](https://ably.com/docs/channels) - + ### 2. For Parameter Validation Errors @@ -122,26 +127,26 @@ You may see one of these messages: - Context parameters must be arrays of objects 3. **Validate channel names** against [naming requirements](https://ably.com/docs/channels#name-syntax) 4. **Check SDK documentation** for specific parameter formats - + ### 3. For .NET SDK Serialization Errors If you see "Unable to read from transport: msg=invalid websocket message (decode failure)": - + 1. **Check your custom serializers** - ensure enums serialize as integers, not strings 2. **Verify protocol message format** - action fields must be integers 3. **Review serialization configuration** for default settings -4. See the [.NET SDK serialization documentation](https://ably.com/docs/sdk/dotnet#custom-serialization) +4. Ensure your JSON serializer doesn't convert numeric enums to strings ### 4. For Push Notification Recipient Limits If you see "Total recipients exceeds maximum allowed 1000": - + 1. **Batch your recipients** in groups of 1000 or fewer 2. **Implement batching logic** in your application -3. See [Push notification limits documentation](https://ably.com/docs/push/publish#recipient-limits) +3. See [Push notification documentation](https://ably.com/docs/push/publish) ### 5. For Chat SDK Feature Errors @@ -150,8 +155,9 @@ If you see "Total recipients exceeds maximum allowed 1000": - Enable presence for presence operations - Enable typing for typing indicators - Enable occupancy for occupancy tracking -3. See [Chat room configuration documentation](https://ably.com/docs/chat/rooms#room-options) - + - Enable reactions for reaction features +3. See [Chat room configuration documentation](https://ably.com/docs/chat/rooms) + ### 6. For Timeserial Format Errors @@ -159,8 +165,8 @@ If you see errors about invalid timeserials: 1. **Check format**: Must contain `@` and `-` characters 2. **Structure**: `@-` 3. **Components**: All parts must be valid integers -4. See [Timeserial documentation](https://ably.com/docs/metadata-stats/metadata/subscribe#serial) - +4. See [Message ordering documentation](https://ably.com/docs/metadata-stats/metadata/subscribe#serial) + ## Automatic Handling @@ -171,7 +177,7 @@ Ably SDKs do not automatically retry 40000 errors as they indicate issues with y With default settings (`queueMessages: true`), messages are automatically queued during temporary disconnections, so you should rarely see state-related 40000 errors in normal operation. - + ## Prevention @@ -183,7 +189,7 @@ With default settings (`queueMessages: true`), messages are automatically queued - **Use current SDK versions** to benefit from improved error handling - **Test serialization** if using custom serializers in .NET SDK - + ## Performance Impact @@ -193,15 +199,30 @@ This error prevents the specific operation but doesn't affect: - Other clients or connections - Message history already stored +## Related Errors + +• **[80000 - Connection Failed](https://help.ably.io/error/80000)** + Connection-level failures that may lead to suspended state and 40000 errors + +• **[80002 - Connection Suspended](https://help.ably.io/error/80002)** + The suspended state that triggers "Unable to publish" 40000 errors + +• **[80003 - Connection Disconnected](https://help.ably.io/error/80003)** + Temporary disconnection that may cause 40000 if queueing is disabled + +• **[90000 - Channel Operation Failed](https://help.ably.io/error/90000)** + Channel-specific failures that may manifest as 40000 in some cases + +• **[40101 - Invalid API Key](https://help.ably.io/error/40101)** + Authentication errors that are more specific than general 40000 + ## Related Resources - [Connection state management](https://ably.com/docs/realtime/connection) - [Channel parameters documentation](https://ably.com/docs/channels/options) -- [Push notification limits](https://ably.com/docs/push/publish#recipient-limits) -- [Chat room configuration](https://ably.com/docs/chat/rooms#room-options) -- [.NET SDK serialization](https://ably.com/docs/sdk/dotnet#custom-serialization) +- [Push notification limits](https://ably.com/docs/push/publish) +- [Chat room configuration](https://ably.com/docs/chat/rooms) - [Message queueing behavior](https://ably.com/docs/realtime/connection#queue-messages) -- Related errors: [80000](./80000-connection-failed.mdx), [80002](./80002-connection-suspended.mdx), [90000](./90000-channel-operation-failed.mdx) ## Need Further Help? @@ -223,42 +244,45 @@ Our team will help you resolve this issue as quickly as possible. + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/40001-invalid-request-body.mdx b/src/pages/docs/platform/errors/codes/40001-invalid-request-body.mdx index b0d9d68be7..7dbf9b184f 100644 --- a/src/pages/docs/platform/errors/codes/40001-invalid-request-body.mdx +++ b/src/pages/docs/platform/errors/codes/40001-invalid-request-body.mdx @@ -1,13 +1,13 @@ - + - + # Error 40001: Invalid request body @@ -39,38 +39,45 @@ You may encounter one of these specific error messages: - "Invalid token request body while parsing authentication request; no nonce specified (nonce is required to prevent replay attacks)" - "unable to add message reaction; type is invalid" - "unable to add message reaction; name is empty" +- "unable to delete message reaction; type is empty" - "invalid JSON data" - "invalid MessagePack data" - "invalid utf-8 data" - "missing content-type" - "invalid response content-type" +- "invalid room configuration: [reason]" +- "Typing heartbeatThrottle must be greater than 0" +- "cannot delete reaction of type [type] without a name" +- "Raw message reactions are not enabled" ## Common Causes 1. **Malformed request body** (40% of cases) - - Invalid JSON syntax + - Invalid JSON syntax (missing quotes, brackets, or commas) - Improperly encoded MessagePack data - Invalid UTF-8 encoding in text fields - + - MessagePack used where only JSON is supported (e.g., LiveObjects API) + 2. **Missing required fields** (35% of cases) - - Empty message text in chat operations - - Missing keyName in token requests - - Missing reaction name or type - - Missing nonce in non-key-authenticated token requests - + - Empty `text` field in chat messages + - Missing `keyName` in token requests + - Missing `nonce` in non-key-authenticated token requests + - Missing `type` or `name` in reactions + 3. **Missing or incorrect Content-Type header** (15% of cases) - No Content-Type header in request - Content-Type doesn't match actual request format - - Using unsupported content types (e.g., plain text, form-encoded) - + - Using unsupported content types (plain text, form-encoded, octet-stream) + 4. **Invalid configuration values** (10% of cases) - - Non-positive typing throttle values + - Non-positive typing throttle values (must be > 0) - Invalid reaction types - Incompatible room configuration options - + - Raw reactions used without enabling in room options + ## Resolution Steps @@ -78,42 +85,52 @@ You may encounter one of these specific error messages: - Ensure your JSON is properly formatted using a JSON validator - Check for common syntax errors like missing quotes, commas, or brackets - If using MessagePack, verify your encoding is correct - + - Note: LiveObjects API currently only supports JSON, not MessagePack + + 2. **Review required fields for your operation** For **chat messages**: - Ensure the `text` field is present and not empty - Include all required metadata fields - + For **token requests**: - Include the `keyName` parameter - Add a unique `nonce` value for non-key-authenticated requests - + - Ensure timestamp is formatted as string or number + + For **reactions**: - - Provide both `type` and `name` fields when required - - Use only valid reaction types as documented - + - Provide `type` field (required for all reactions) + - Include `name` field for non-unique reaction types + - Only use `count` field with "Multiple" type reactions + - Enable raw reactions in room options before using + + 3. **Set proper HTTP headers** - Include `Content-Type: application/json` for JSON requests - - Use `Content-Type: application/x-msgpack` for MessagePack + - Use `Content-Type: application/x-msgpack` for MessagePack (where supported) - Ensure character encoding is UTF-8 - + 4. **Check SDK-specific requirements** - Review the API documentation for your specific SDK - Verify you're using the correct method signatures - Ensure proper serialization settings in your language - + - Keep your SDK updated to the latest version + 5. **Debug with minimal payload** - Start with the simplest valid request - Gradually add optional parameters - Log the exact request body being sent - + - Check for batch operation error masking (40020 may hide 40001 errors) + + ## Automatic Handling @@ -125,16 +142,31 @@ This is a client error that will not be automatically retried by Ably SDKs. You - Use strongly-typed SDK methods where available - Implement request validation in your application layer - Test with various payload sizes and character sets -- Keep your SDK updated to the latest version - +- Be aware of API-specific limitations (e.g., LiveObjects is JSON-only) +- For batch operations, check the batchResponse field for individual errors + + ## Related Resources - [Ably REST API Documentation](https://ably.com/docs/api/rest-api) -- [Ably Chat API Documentation](https://ably.com/docs/chat) +- [Ably Chat SDK Documentation](https://ably.com/docs/chat/setup) - [Token Authentication Documentation](https://ably.com/docs/auth/token) -- [Message Encoding Documentation](https://ably.com/docs/general/encodings) -- Related errors: [40003](https://help.ably.io/error/40003), [40012](https://help.ably.io/error/40012), [40013](https://help.ably.io/error/40013) +- [REST API Token Request Specification](https://ably.com/docs/api/token-request-spec) + +## Related Errors + +• **[40003 - Invalid Parameter Value](https://faqs.ably.com/error-40003)** + More specific validation errors for individual parameter values + +• **[40012 - Invalid Client ID](https://help.ably.io/error/40012)** + Client ID validation errors in messages and presence operations + +• **[40013 - Invalid Message Data](https://help.ably.io/error/40013)** + Message data encoding and format validation errors + +• **[40020 - Batch Response Contains Errors](https://help.ably.io/error/40020)** + May mask individual 40001 errors in batch operations - check batchResponse field ## Need Further Help? @@ -155,22 +187,32 @@ Our team will help you resolve this issue as quickly as possible. - + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/40400-resource-not-found.mdx b/src/pages/docs/platform/errors/codes/40400-resource-not-found.mdx index fc6f7eff41..9edd0ad53e 100644 --- a/src/pages/docs/platform/errors/codes/40400-resource-not-found.mdx +++ b/src/pages/docs/platform/errors/codes/40400-resource-not-found.mdx @@ -1,20 +1,20 @@ - + - + # Error 40400: Resource not found ## What Happened -The system could not find the resource you requested - typically an API key component, application, rule, device, or other identifier doesn't exist or is no longer available. +The requested resource could not be found - most commonly this means your API key is invalid or malformed, though it can also indicate other missing resources like channels, rules, or devices. ## Quick Reference @@ -24,104 +24,130 @@ The system could not find the resource you requested - typically an API key comp ## Quick Fix -- Double-check your API key for typos - especially missing or extra characters -- Verify you're using the correct environment (production vs sandbox) -- Confirm the resource exists in your [Ably dashboard](https://ably.com/dashboard) +- **Authentication issues**: Check your API key for typos - even one missing character causes this error +- **Wrong environment**: Verify you're using production keys for production, sandbox keys for sandbox +- **Dashboard verification**: Confirm the resource exists in your [Ably dashboard](https://ably.com/dashboard) ## Error Messages -You may see one of these messages: -- "No application found with id {appId}" -- "No such key {keyId}" -- "invalid key parameter" -- "Device with Id '{deviceId}' is not found" -- "rule {ruleId} not found" -- "Unable to locate subscription" -- "No link to the first/current page of results" -- "Message not found" -- "Could not find path: {path}" -- Various resource-specific "not found" messages +You may encounter these messages: + + +- "No application found with id {appId}" - Your API key's app ID portion is invalid +- "No key found with id {keyId}" - Your API key's key ID portion is invalid +- "invalid key parameter" - API key format is incorrect (missing colon separator) +- "Device with Id '{deviceId}' is not found" - Push device registration missing +- "rule {ruleId} not found" - Integration rule deleted or doesn't exist +- "Unable to locate subscription" - Subscription not found +- "No link to the first/current page of results" - Pagination issue +- "Message not found" - Message not in persistence layer +- "Could not find path: {path}" - Invalid API endpoint ## Common Causes - + + +### 1. Invalid API Key Components (Most common - 80% of cases) + +**API keys have three parts**: `appId.keyId:keySecret` +Example: `xVLyHw.Ke5A1w:dTfJtg-OP2L8B...` -1. **Invalid API key components** (Most common) - - Missing characters from the app ID (first part before the dot) - - Missing characters from the key ID (part between dot and colon) - - Incorrect API key format (missing colon separator) - - Using a deleted or regenerated key +Common mistakes: +- **Missing characters from app ID** (the part before the dot) → "No application found with id" +- **Missing characters from key ID** (between dot and colon) → "No key found with id" +- **Missing colon separator** → "invalid key parameter" +- **Using a deleted or regenerated key** -2. **Wrong environment or region** - - Using production key in sandbox environment - - Using sandbox key in production - - Incorrect regional endpoint +### 2. Wrong Environment or Region (15% of cases) -3. **Resource has been deleted** - - API key was regenerated or deleted - - Push device registration removed - - Integration rule deleted - - Application removed +- Using production API key in sandbox environment +- Using sandbox API key in production environment +- Incorrect regional endpoint (e.g., using US key with EU endpoint) -4. **Pagination issues** - - Missing or malformed pagination links - - Empty result sets - - Manually constructed pagination URLs +### 3. Resource Has Been Deleted (5% of cases) -5. **System initialization problems** - - Required monitors not available - - Configuration resources missing - - Dependencies not initialized +- API key was regenerated in dashboard (old key no longer valid) +- Push device registration was removed +- Integration rule was deleted +- Application was removed from account ## Resolution Steps - - -1. **Verify your API key structure** - - API keys have the format: `appId.keyId:keySecret` - - Example: `xVLyHw.Ke5A1w:dTfJtg-OP2L8B...` - - The app ID is before the first dot (`xVLyHw`) - - The key ID is between the dot and colon (`Ke5A1w`) - - Ensure no characters are missing from any part - -2. **Check in your Ably dashboard** - - Log into [https://ably.com/dashboard](https://ably.com/dashboard) - - Navigate to your app - - Go to the "API Keys" tab - - Copy the complete key including all three parts - - Verify you're in the correct environment (production/sandbox) - -3. **For device registration errors** - - Confirm the device ID exists in Push Notifications → Devices - - Check if the device was recently unregistered - - Ensure the device registration hasn't expired - -4. **For pagination errors** - - Use the pagination links provided in API responses - - Don't manually construct pagination URLs - - Check if the result set contains any items - -5. **For integration rule errors** - - Navigate to Integrations in your dashboard - - Verify the rule ID exists and is active - - Check if the rule was recently modified or deleted + -## Automatic Handling +### 1. Verify Your API Key Structure + +API keys must have all three components: +- **App ID**: Before the first dot (e.g., `xVLyHw`) +- **Key ID**: Between dot and colon (e.g., `Ke5A1w`) +- **Key Secret**: After the colon (e.g., `dTfJtg-OP2L8B...`) + + +**Important**: If you see "No application found" or "No key found", your API key is likely missing characters. Even one missing character will cause authentication to fail. + +### 2. Check Your Ably Dashboard + + +1. Log into [https://ably.com/dashboard](https://ably.com/dashboard) +2. Navigate to your app +3. Go to the "API Keys" tab +4. Copy the **complete** key (all three parts) +5. Verify you're in the correct environment: + - **Production**: Uses `rest.ably.io` + - **Sandbox**: Uses `sandbox-rest.ably.io` + +### 3. For Push Device Errors + + +- Navigate to Push Notifications → Devices in your dashboard +- Confirm the device ID exists +- Check if the device registration expired +- Re-register the device if necessary + +### 4. For Integration Rule Errors - + +- Go to Integrations in your dashboard +- Verify the rule ID exists and is active +- Check if the rule was recently modified or deleted +- Recreate the rule if needed -This is a client error that will not be automatically retried. The resource must exist before the operation can succeed. SDKs will not attempt to recover from this error as it indicates a permanent issue with the request. +### 5. For Pagination Errors + + +- Use the pagination links provided in API responses +- Don't manually construct pagination URLs +- Check if the result set is empty (no error, just no results) + +## Automatic Handling + + +This is a permanent client error that SDKs will not automatically retry. The missing resource must be fixed before the operation can succeed. Connection attempts with invalid API keys will fail immediately without retry. ## Prevention - + +- **Store API keys securely**: Use environment variables to avoid typos +- **Validate before use**: Check API key format before initialization +- **Monitor key rotation**: Update all services when regenerating keys +- **Use the dashboard**: Regularly verify resources exist +- **Test after changes**: Verify connections after any key regeneration + +## Related Errors -- Store API keys in environment variables to avoid typos -- Implement proper error handling for 404 responses -- Validate resource IDs before making API calls -- Use the Ably dashboard to manage and verify resources -- Keep track of resource deletions and updates -- Test API keys after regeneration + + +• **[40101 - Authentication Failed](https://help.ably.io/error/40101)** + Occurs when API key secret is incorrect (different from 40400's missing resource issue) + +• **[40103 - Invalid Use of Basic Auth](https://help.ably.io/error/40103)** + Related authentication error when using API keys over non-TLS connections + +• **[40102 - Token Expired](https://help.ably.io/error/40102)** + Token-based authentication failure that may appear similar to API key issues + +• **[80000 - Connection Failed](https://help.ably.io/error/80000)** + General connection failure that may follow authentication resource errors ## Related Resources @@ -129,7 +155,7 @@ This is a client error that will not be automatically retried. The resource must - [API key management](https://ably.com/docs/auth/basic) - [Push notifications setup](https://ably.com/docs/push) - [Integration rules](https://ably.com/docs/general/integrations) -- [Pagination in REST API](https://ably.com/docs/rest/usage#pagination) +- [Environment setup](https://ably.com/docs/basics/use-ably#account) ## Need Further Help? @@ -150,44 +176,47 @@ Our team will help you resolve this issue as quickly as possible. - + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/50000-internal-server-error.mdx b/src/pages/docs/platform/errors/codes/50000-internal-server-error.mdx index 5376d2695f..4a987c5779 100644 --- a/src/pages/docs/platform/errors/codes/50000-internal-server-error.mdx +++ b/src/pages/docs/platform/errors/codes/50000-internal-server-error.mdx @@ -1,29 +1,32 @@ - + - + # Error 50000: Internal server error ## What Happened + An unexpected error occurred within Ably's servers while processing your request. ## Quick Reference + | Error Code | HTTP Status | Category | Retryable | |------------|-------------|----------|-----------| -| 50000 | 500 | Server Error | Yes - temporary server issue | +| 50000 | 500 | Server Error (Infrastructure) | Yes - temporary server issue | ## Quick Fix + - No immediate action required - Ably SDKs handle retry automatically - Check [Ably status page](https://status.ably.com) if error persists beyond 2 minutes -- Note the request ID from error details for support if needed +- Note the request ID and exact error message for support if needed ## Error Messages @@ -32,106 +35,175 @@ You may see one of these messages: - "Unknown error" - "Transport error" - "Unable to process request" -- Additional context-specific messages depending on the operation +- "Timeout waiting for transport to indicate itself viable" +- "Error executing request" +- "Monitor stopped" +- "Unable to connect to server" + ## Common Causes 1. **Temporary service disruption** (60% of cases) - Brief internal processing issues - Transient connectivity problems between internal services - - Temporary resource constraints + - Service initialization or shutdown scenarios + 2. **Database or infrastructure issues** (25% of cases) - Connection pool exhaustion - - Query timeouts - - Service initialization problems - -3. **Unexpected conditions** (15% of cases) - - Malformed internal responses - - Protocol violations - - Edge cases in request processing + - Query timeouts exceeding 10 second limit + - State cache management problems + + +3. **Transport or protocol problems** (10% of cases) + - WebSocket connection failures + - Heartbeat timeout (after 25 seconds without server activity) + - Protocol validation errors + + +4. **Push notification services** (5% of cases) + - FCM token request failures + - Device registration issues on mobile platforms + - Platform-specific push service problems + ## Resolution Steps 1. **For transient errors (most cases)** - Ably SDKs automatically retry with appropriate backoff - No action required unless error persists beyond 2 minutes - - Monitor your application logs for frequency + - Connection will transition through states: disconnected → connecting → connected + 2. **For persistent errors (lasting >2 minutes)** - Check https://status.ably.com for any ongoing incidents - - Review recent changes to your implementation - - Note the exact error message and any request IDs - - -3. **Gather diagnostic information** - - Record the timestamp of the error - - Note which operation triggered the error - - Check if the error affects all operations or specific ones - - Monitor if error rate is increasing + - Note if error affects all operations or specific channels + - Connection may enter `suspended` state after 2 minutes of failures + - In suspended state, SDK retries every 30 seconds instead of 15 seconds + + +3. **For WebSocket or transport errors** + - SDK will automatically fall back: WebSocket → HTTP streaming → HTTP polling + - Ensure your firewall allows WebSocket connections on ports 80 and 443 + - Check network connectivity and proxy settings + + +4. **Gather diagnostic information** + - Record the exact timestamp and error message + - Note which SDK and version you're using + - Check if error correlates with high traffic or specific operations + - Monitor error frequency - isolated vs recurring pattern ## Automatic Handling -Ably SDKs automatically retry server errors with exponential backoff. The SDK will: -- Retry the operation with increasing delays -- Continue retrying for transient failures -- Maintain connection state during retries -- Queue messages when appropriate (for publish operations) +Ably SDKs automatically handle server errors with the following behavior: +- Retry operations with exponential backoff (starting at ~15 seconds) +- Attempt connection to alternate datacenters if initial fails +- Queue messages during temporary disconnections (when `queueMessages` is enabled) +- Restore message continuity if reconnected within 2 minutes +- Transition to `suspended` state after 2 minutes, continuing retry every 30 seconds -Manual retry logic is not needed - let the SDK handle recovery. - +Manual retry logic is not needed - the SDK manages recovery transparently. + ## Code Examples -### Monitoring for persistent errors +### Monitoring connection state during server errors ```javascript -// Monitor connection state for persistent issues -ably.connection.on('failed', (stateChange) => { +// Monitor connection state transitions +ably.connection.on('disconnected', (stateChange) => { if (stateChange.reason?.code === 50000) { - console.error('Persistent server error:', stateChange.reason); - // Log to your monitoring system - // Check https://status.ably.com + console.log('Server error detected, SDK will retry automatically'); + // Log to your monitoring system but don't manually retry } }); -// Connection will automatically retry - no manual intervention needed +ably.connection.on('suspended', (stateChange) => { + // After 2 minutes of failures, connection enters suspended state + console.log('Connection suspended after prolonged server issues'); + // Check https://status.ably.com for incidents +}); + ably.connection.on('connected', () => { - console.log('Recovered from server error'); + console.log('Successfully recovered from server error'); }); ``` - + -### Handling in request/response operations +### Handling server errors in REST operations ```javascript try { - const tokenDetails = await ably.auth.requestToken(); + const stats = await ably.stats(); } catch (err) { if (err.code === 50000) { - // Server error - will be retried automatically by SDK - console.error('Server error during token request:', err.message); - // The SDK will handle retry - just log for monitoring + // Server error - SDK already retried 3 times to different endpoints + console.error('Persistent server error after retries:', err.message); + // Check status page, don't implement manual retry } } ``` - + + +### Mobile push notification error handling + +```javascript +// React Native / Mobile SDKs +try { + await ably.push.activate(); +} catch (err) { + if (err.code === 50000 && err.message.includes('FCM')) { + // Push service initialization failed + console.error('Push notification service error:', err.message); + // May need to check device settings or network connectivity + } +} +``` + + +## Prevention + +While server errors cannot be completely prevented, you can minimize impact: +- Implement connection state monitoring to track issues +- Use presence to detect and handle connection drops gracefully +- Enable message queueing (`queueMessages: true`) for publish resilience +- Monitor your application's error rates to detect patterns +- Consider implementing fallback UI states for degraded connectivity ## Performance Impact This error may cause: -- Temporary delays in message delivery -- Brief connection interruptions -- Queuing of outbound messages (automatically handled) -- Possible presence state updates after recovery +- Temporary message delivery delays (typically seconds to minutes) +- Brief connection state transitions (disconnected → connecting → connected) +- Automatic message queueing during disconnections +- Presence member updates after recovery +- Possible message redelivery if connection resumed within 2 minutes -The SDK handles recovery transparently, minimizing impact on your application. +The SDK handles these scenarios automatically to minimize application impact. + ## Related Resources + - [Ably system status](https://status.ably.com) -- [Connection state management](https://ably.com/docs/realtime/connection) -- [Error handling guide](https://ably.com/docs/best-practice/error-handling) +- [Connection states and recovery](https://ably.com/docs/connect/states) +- [Connection overview](https://ably.com/docs/connect/) - [Platform reliability](https://ably.com/four-pillars-of-dependability) +- [Error codes reference](https://faqs.ably.com/ably-error-codes) + +## Related Errors + +• **[40000 - Bad Request](https://help.ably.io/error/40000)** + May occur alongside 50000 when internal issues cause request validation problems + +• **[50003 - Internal Timeout](https://help.ably.io/error/50003)** + Related timeout scenario when internal operations exceed time limits + +• **[80000 - Connection Failed](https://help.ably.io/error/80000)** + Connection-level failure that may result from persistent 50000 errors + +• **[91000 - Channel Operation Failed](https://help.ably.io/error/91000)** + Channel-specific failures that can occur due to underlying server errors ## Need Further Help? @@ -153,34 +225,66 @@ Our team will help you resolve this issue as quickly as possible. + + + + + + \ No newline at end of file From 22f2472b1211bfe5d7f283ab1b581373bb9b9e09 Mon Sep 17 00:00:00 2001 From: Matthew O'Riordan Date: Sun, 24 Aug 2025 22:28:09 +0200 Subject: [PATCH 4/6] Update Spaces documentation New category just defined for Spaces + index page regenerated --- src/pages/docs/platform/errors/codes.mdx | 934 ++++++------------ .../codes/101000-space-name-missing.mdx | 203 +++- .../errors/codes/101001-not-entered-space.mdx | 77 +- .../101002-lock-request-already-exists.mdx | 118 ++- .../errors/codes/101003-lock-is-locked.mdx | 107 +- .../errors/codes/101004-lock-invalidated.mdx | 164 ++- 6 files changed, 742 insertions(+), 861 deletions(-) diff --git a/src/pages/docs/platform/errors/codes.mdx b/src/pages/docs/platform/errors/codes.mdx index b8383daaf0..06bc17ff86 100644 --- a/src/pages/docs/platform/errors/codes.mdx +++ b/src/pages/docs/platform/errors/codes.mdx @@ -5,802 +5,426 @@ redirect_from: - /docs/errors/codes --- -Use the error codes provided, which include descriptions, possible causes, and solutions, to troubleshoot issues effectively. +When working with Ably's realtime infrastructure, your application may encounter various error codes that help identify and resolve issues. This comprehensive reference provides detailed information about all error codes across Ably's platform and SDKs. - +Each error code follows a consistent format with specific ranges indicating the error category. The error messages and behavior are consistent across all Ably SDKs, making it easier to debug issues regardless of your chosen platform. For example, error 40012 always indicates an invalid client ID issue, whether you're using JavaScript, Python, Ruby, or any other SDK. -## 500: Internal error +## Core Pub/Sub Messaging -This error occurs when there is an issue within Ably's system. +**[0: Generic client error](/docs/platform/errors/codes/0-generic-client-error)** +The SDK encountered an error during client-side validation or a generic error condition occurred where no specific error code was available. -## 50000: Internal error +**[1: Unknown error](/docs/platform/errors/codes/1-unknown-error)** +The SDK encountered an error code from the Ably service that it doesn't recognize, typically indicating a version mismatch between your SDK and the API. -This error occurs when there is an issue within Ably's system. +**[40000: Bad request](/docs/platform/errors/codes/40000-bad-request)** +Your request cannot be processed because it doesn't meet Ably's requirements - this could be due to invalid parameters, wrong connection state, missing prerequisites, or protocol violations. -## 10000: No error +**[40001: Invalid request body](/docs/platform/errors/codes/40001-invalid-request-body)** +The request sent to Ably contains invalid, malformed, or incomplete data that cannot be processed. -This error code indicates that the attempted action was successful and no issues occurred; there will be additional info in the `message` property about the successful action. +**[40003: Invalid Parameter Value](/docs/platform/errors/codes/40003-invalid-parameter-value)** +A parameter in your request contains an invalid value that doesn't meet Ably's requirements. -## 20000: General error code +**[40004: Invalid header](/docs/platform/errors/codes/40004-invalid-header)** +The server rejected your request due to an invalid or malformed header value that couldn't be parsed or validated. -This error code is a generic response used when the Ably [protocol](/docs/protocols) requires an `errorInfo` object, even though no actual issue has occurred. The message property may contain additional details about the successful action. +**[40006: Invalid connection ID](/docs/platform/errors/codes/40006-invalid-connection-id)** +Message contains an invalid connectionKey, mismatched connectionId, or the server cannot validate your connection identity -## 40000: Bad request +**[40008: Invalid content length](/docs/platform/errors/codes/40008-invalid-content-length)** +The request body size doesn't match the Content-Length header value declared in your HTTP request. -This error occurs when Ably cannot understand the request due to a malformed structure or other issues with the request format. +**[40009: Message size exceeded](/docs/platform/errors/codes/40009-message-size-exceeded)** +Your message exceeded the maximum size allowed for your Ably package tier. -An example of this error is when a message is published while the connection is in a [suspended state](/docs/connect/states#connection-states). +**[40010: Invalid channel name](/docs/platform/errors/codes/40010-invalid-channel-name)** +The channel name you provided doesn't meet Ably's naming requirements or contains invalid characters or qualifiers. -## 40001: Invalid request body +**[40011: Stale ring state or invalid data payload](/docs/platform/errors/codes/40011-stale-ring-state)** +This error has two distinct causes: either the channel enumeration API encountered a cluster state change during pagination, or a message contained an unsupported data type. -This error occurs when a request contains invalid content, such as incorrect [data types](/docs/api/realtime-sdk/types#data-types) or missing required objects. It is most likely caused by missing required fields or incorrect data formats when sending a request to Ably. +**[40013: Invalid message data or encoding](/docs/platform/errors/codes/40013-invalid-message-data-or-encoding)** +The SDK cannot encode or decode your message because the data type is unsupported or the encoding process failed. -An example of this error is a missing field, such as a `keyName` in a [token request](/docs/api/token-request-spec#tokenrequest-format). +**[40014: Resource disposed](/docs/platform/errors/codes/40014-resource-disposed)** +The operation failed because the requested resource (such as a channel, connection, or internal component) has already been disposed or closed. -## 40003: Invalid parameter value +**[40018: Delta decode failure](/docs/platform/errors/codes/40018-delta-decode-failure)** +The SDK couldn't decode a delta-compressed message, which means the channel needs to reattach to restore message continuity. -This error occurs when an invalid value is sent in the request. It may be caused by either user input or the SDK sending incorrect parameters. +**[40019: Missing Plugin](/docs/platform/errors/codes/40019-missing-plugin)** +The SDK requires a plugin or module that isn't installed or included in your build. -Additional examples of the `40003` error code output include: +**[40020: Batch operation partial failure](/docs/platform/errors/codes/40020-batch-operation-partial-failure)** +Your batch request completed with partial success—some operations in the batch succeeded while others failed. -* **40003: Excessive value for TTL** -This error occurs when the [TTL](/docs/api/rest-sdk/authentication#token-request) set for a token parameter exceeds the maximum allowed value of 24 hours. -* **40003: Excessive value for TTL (revocation is enabled on this key)** -This error occurs when [revocation](/docs/auth/revocation#revocable-tokens) is enabled, revocable tokens are limited to a TTL of 1 hour instead of 24 hours. +**[40022: Invalid Resource or Deprecated Feature](/docs/platform/errors/codes/40022-invalid-resource-deprecated-feature)** +Request failed because you're either trying to use a deprecated feature (API Streamer) or your resource validation failed in the Control API -## 40005: Invalid credentials +**[40023: Protocol Version Required](/docs/platform/errors/codes/40023-protocol-version-required)** +Your application tried to use a feature that requires a newer version of the Ably protocol than your current SDK supports. -This error occurs when the [API key](/docs/auth#api-keys) or [token](/docs/auth/token) used to initialize the library is invalid. -**Resolution:** The following steps can help resolve this issue: +**[40024: Channel Mode Required](/docs/platform/errors/codes/40024-channel-mode-required)** +The channel you're trying to use for LiveObjects operations doesn't have the required channel mode configured. -* API key initialization: -** Ensure you are the account's **admin** or **owner**. -** In your [Ably dashboard](https://ably.com/accounts/any) to the **API keys** tab. -** Use one of these API keys instead of your current one or create a [new API key](/docs/platform/account/app/api#create) with the necessary permissions and privileges and use that to instance the SDK. -* Token initialization: -** If you are using [token authentication](/docs/auth/token), ensure you are correctly requesting a valid token before using it with Ably. +**[40030: Invalid publish request](/docs/platform/errors/codes/40030-invalid-publish-request)** +Your publish request to Ably was malformed and could not be processed. -## 40006: Invalid connectionId +**[40031: Invalid message ID](/docs/platform/errors/codes/40031-invalid-message-id)** +The message ID you specified doesn't meet the requirements for idempotent message publishing. -This error occurs when a message is published with an invalid or mismatched [`connectionId`](/docs/messages#properties). +**[40032: Invalid extras field](/docs/platform/errors/codes/40032-invalid-extras-field)** +Your message contains fields in the extras object that are not allowed by Ably, or the allowed fields have incorrect values. -Examples of this error are when: -* A client attempts to publish a message using a malformed `connectionId`. -* A client publishes a realtime message with a `connectionId` that does not match the currently active connection. -* A connection is identified, but the resolved `clientId` is missing or incorrect (due to authentication issues or an explicitly provided, but incorrect, `clientId`). +**[40099: Internal Testing Error](/docs/platform/errors/codes/40099-internal-testing-error)** +The system encountered an internal testing or development error that should not occur during normal operations. -## 40009: Maximum message length exceeded +**[40500: Method Not Allowed](/docs/platform/errors/codes/40500-method-not-allowed)** +The HTTP method you used (GET, POST, PUT, DELETE, etc.) is not supported for this endpoint. -This error occurs when the message being published exceeds the maximum size allowed set by the [limits](/docs/platform/pricing/limits#app-limits) for your current [package](/docs/pricing#packages). +**[49900: Call cancelled](/docs/platform/errors/codes/49900-call-cancelled)** +A request was cancelled before it could complete, typically due to the client closing the connection or explicitly cancelling the operation. -## 40010: Invalid channel name +**[65536: Not an error code](/docs/platform/errors/codes/65536-not-an-error-code)** +65536 is not an error code but a configuration constant representing the maximum message size (64KB) allowed by the Ably protocol -This error occurs when a [channel name](/docs/channels#use) does not meet the required format or contains invalid characters. +**[90000: Channel operation failed](/docs/platform/errors/codes/90000-channel-operation-failed)** +A channel operation couldn't be completed due to conflicting requests, invalid state, or timing issues with attach/detach operations -## 40011: Stale ring state +**[90001: Channel operation failed (invalid channel state)](/docs/platform/errors/codes/90001-channel-operation-failed-invalid-state)** +You attempted to perform an operation on a channel that isn't in the correct state for that operation. -This error occurs when using the channel [enumeration](/docs/api/rest-api#enumeration-rest) API and the state of the cluster changes between successive calls, causing a pagination sequence to become invalid. Note: This issue does not occur if the enumeration request is fully satisfied within the first response page. +**[90003: Unable to recover channel (messages expired)](/docs/platform/errors/codes/90003-unable-to-recover-channel)** +Channel recovery failed because the messages needed for recovery have expired and are no longer available in Ably's message history -## 40012: Invalid `clientId` +**[90004: Message Limit Exceeded](/docs/platform/errors/codes/90004-message-limit-exceeded)** +Your channel couldn't recover all missed messages because the number of messages exceeded the system's recovery limit. -This error occurs when a `clientId` is invalid due to disallowed characters or a mismatch between the `clientId` specified in the request and the one assigned in the authentication [token](/docs/auth/token). +**[90005: Channel Recovery Epoch Not Found](/docs/platform/errors/codes/90005-channel-recovery-epoch-not-found)** +The channel couldn't recover its previous state because the requested recovery point no longer exists on Ably's servers. -Examples of this error are when: +**[90007: Channel operation timeout](/docs/platform/errors/codes/90007-channel-operation-timeout)** +A channel attach or detach operation didn't complete within the configured timeout period, typically 10 seconds. -* The client attempts to use `*` as a `clientId`, which is not allowed because `*` is used as a [wildcard](/docs/auth/capabilities#wildcards) in capability expressions. -* A client tries to assume an ID of `foo` for an operation, but the token they are using specifies an ID of `bar`. +**[90010: Channel limit exceeded](/docs/platform/errors/codes/90010-channel-limit-exceeded)** +You've exceeded the maximum number of channels allowed in a single request or connection. -## 40013: Invalid message data or encoding +**[90099: Generic discontinuity](/docs/platform/errors/codes/90099-generic-discontinuity)** +A discontinuity has been detected in the message stream, indicating a gap or break in the sequence of messages on this channel. -This error occurs when the SDK is unable to encode the [message payload](/docs/messages) due to an unsupported data type. +**[91000: Presence requires client ID](/docs/platform/errors/codes/91000-presence-requires-client-id)** +You attempted to enter, update, or leave a presence channel without having a client ID configured for your connection. -An example of this error is when a client attempts to publish a payload that includes something that isn't serializable by an Ably SDK. +**[91001: presence-channel-invalid-state](/docs/platform/errors/codes/91001-presence-channel-invalid-state)** +The presence operation could not be completed because the channel is not in a valid state to accept presence updates. -**Resolution:** Try marshalling the payload as JSON or MsgPack before publishing. +**[91004: Presence auto-reenter failed](/docs/platform/errors/codes/91004-presence-auto-reenter-failed)** +The SDK was unable to automatically re-enter your client into the presence set after reconnecting to the channel. -## 40015: Invalid deviceId +**[91005: Presence state out of sync](/docs/platform/errors/codes/91005-presence-state-out-of-sync)** +The presence state for this channel has become desynchronized and cannot provide accurate member information -This error occurs when the ID property in a [DeviceDetails](/docs/api/rest-sdk/push-admin#device-details) object, sent during a push notification registration request, is invalid. The ID must be a string. +**[91100: Member implicitly left presence channel](/docs/platform/errors/codes/91100-member-implicitly-left-presence)** +A presence member was automatically removed from a channel when their connection ended unexpectedly or the system detected an inconsistent state -## 40016: Invalid message name +**[92000: LiveObjects validation error](/docs/platform/errors/codes/92000-liveobjects-validation-error)** +A LiveObjects operation failed validation due to invalid data, missing state, or synchronization issues. -This error occurs when the `name` [property](/docs/messages#properties) of a message is not a string. The `name` field is used to categorize messages within channels, and it must always be a string. +**[92001: Conflicting Error Code Usage](/docs/platform/errors/codes/92001-conflicting-error-code-usage)** +This error code has two different meanings depending on which Ably feature you're using - Ruby SDK channel encryption issues or LiveObjects limit exceeded. -## 40017: Unsupported protocol version or Invalid API version specified +**[92004: Dual Purpose Cipher or Object Error](/docs/platform/errors/codes/92004-dual-purpose-cipher-object-error)** +This error has two completely different meanings depending on context: 1) Ruby SDK - An unsupported cipher algorithm was specified for encryption, 2) LiveObjects - An attempt was made to access an object that doesn't exist -This error occurs when a request does not specify a protocol version or provides an invalid version in the request parameters of a [Server-Sent Events (SSE)](/docs/protocols/sse) request. This error also occurs when a WebSocket connection to Ably specifies an invalid API version in the request parameters. +**[92005: Duplicate context error](/docs/platform/errors/codes/92005-duplicate-context-error)** +This error code is currently used in two different contexts within Ably's systems. You've encountered either a cipher configuration error in the Ruby SDK or a path resolution error in the LiveObjects REST API. -**Resolution**: Ensure that the request specifies a valid protocol version. Note: You will not see this error when using an Ably SDK, as SDKs automatically use valid versions. +**[92100: Encoding value too long](/docs/platform/errors/codes/92100-encoding-value-too-long)** +The message encoding metadata string exceeded the maximum allowed length of 512 characters. -## 40020: Partial failure in batch operation requests +**[93001: Annotations channel state invalid](/docs/platform/errors/codes/93001-annotations-channel-state-invalid)** +The channel is not in the correct state to perform annotations operations. The channel must be attached before you can use annotations features. -This error occurs when a [batch](/docs/api/rest-api#batch) request partially fails, meaning that some operations succeed while others fail. +**[93002: Mutable Messages feature required](/docs/platform/errors/codes/93002-mutable-messages-feature-required)** +The operation requires the Mutable Messages feature to be enabled, but it's not currently available on this channel. -This error can occur for the following endpoints: +## Authentication & Security -* Revoking tokens: [`POST/revokeTokens`](/docs/api/rest-api#revoke-tokens) -* Publishing messages: [`POST/messages`](/docs/api/rest-api#batch-publish) -* Retrieving presence data: [`GET/presence`](/docs/api/rest-api#batch-presence) +**[40005: Invalid credential](/docs/platform/errors/codes/40005-invalid-credential)** +Your authentication credentials (API key or token) are invalid or incorrectly formatted. -The following example is a batch operation response that includes partial failures. The `error` field indicates that some requests within the batch were unsuccessful, while the `batchResponse` contains individual results for each operation: +**[40012: Invalid client ID](/docs/platform/errors/codes/40012-invalid-client-id)** +Your request contains a client ID that doesn't meet Ably's validation requirements or conflicts with your authenticated identity. - -```json -{ - "error": "new ErrorInfo('Batched response includes errors', 40020, 400)", - "batchResponse": "results" -} -``` - +**[40100: Unauthorized access](/docs/platform/errors/codes/40100-unauthorized-access)** +An action cannot be performed due to a lack of authorization. This is distinct from invalid credentials (40101) or other authentication errors. -## 40022: Invalid resource +**[40101: Invalid credentials](/docs/platform/errors/codes/40101-invalid-credentials)** +Your authentication credentials are invalid, incorrectly formatted, or cannot be verified by Ably's authentication system. -This error occurs when the requested resource is invalid or already exists. It is typically returned by requests to the [Control API](/docs/platform/account/control-api). +**[40102: Incompatible credentials](/docs/platform/errors/codes/40102-incompatible-credentials)** +Your authentication credentials contain mismatched or incompatible information that prevents a successful connection. -Examples of this error include attempting to create a resource that already exists or providing an invalid resource name. +**[40103: Basic authentication requires TLS](/docs/platform/errors/codes/40103-basic-auth-requires-tls)** +Your API key cannot be used over an unencrypted connection for security reasons. -**Resolution:** The following steps can help resolve this issue: -* Ensure that an app with the requested name does not already exist in your account. If it does, use a different name. -* Verify that the [capabilities](/docs/auth/capabilities#capability-operations) listed in the request are valid when creating an API key. +**[40104: Timestamp not current](/docs/platform/errors/codes/40104-timestamp-not-current)** +The timestamp in your authentication request is too far from Ably's current server time, preventing authentication to protect against replay attacks. -## 40023: Action requires a newer protocol version +**[40106: Missing authentication credentials](/docs/platform/errors/codes/40106-missing-auth-credentials)** +The Ably SDK cannot find the authentication credentials needed to connect to Ably or perform the requested operation. -This error occurs when the requested operation is only available in a newer version of the Ably protocol than the one specified in the request. This can happen if the client is using an older version of the Ably SDK that does not support the requested operation. +**[40113: Account blocked](/docs/platform/errors/codes/40113-account-blocked)** +Your Ably account has been blocked or suspended, preventing all access to Ably services. -Examples of this error include attempting to use [channel objects](/docs/liveobjects) or message annotations, updates and deletes from an Ably SDK that does not support protocol version 2. +**[40115: Account request limit exceeded](/docs/platform/errors/codes/40115-account-request-limit-exceeded)** +Your Ably account has exceeded its allocated API request quota, triggering a hard limit that temporarily blocks further requests. -**Resolution:** The following steps can help resolve this issue: -* Upgrade the Ably SDK to a version that supports the requested operation. +**[40121: Token revocation not enabled](/docs/platform/errors/codes/40121-token-revocation-not-enabled)** +You attempted to use token revocation features that are not enabled for your Ably application or account. -## 40030: Invalid publish request (unspecified) +**[40130: Key removed](/docs/platform/errors/codes/40130-key-removed)** +The API key you're using has been permanently removed from your Ably account and cannot be restored. -This error occurs when a [publish request](/docs/pub-sub#publish) is malformed. +**[40131: Key revoked](/docs/platform/errors/codes/40131-key-revoked)** +Your API key has been temporarily suspended (revoked) and cannot be used for authentication until it's restored by an administrator -## 40032: Invalid publish request (impermissible extras field) +**[40132: API key expired](/docs/platform/errors/codes/40132-api-key-expired)** +Your API key has reached its expiration date and can no longer be used for authentication with Ably services. -This error occurs when a published message contains arbitrary fields in the [`extras`](/docs/api/realtime-sdk/messages#extras) payload that are not allowed by the Ably service. The `extras` field is reserved for specific objects related to Ably. +**[40133: Token revocation authorization error](/docs/platform/errors/codes/40133-token-revocation-auth-error)** +You're attempting to revoke tokens using a different API key than the one that originally issued them. -**Resolution:** Place any additional data inside the `headers` field within `extras`. The `headers` field must be a flat object (`map` or equivalent) with no nested structures. If using unenveloped Reactor rules, ensure that header names are in `ASCII`, as they will be converted into HTTP, AMQP, or other protocol headers. +**[40140: Token error (unspecified)](/docs/platform/errors/codes/40140-token-error-unspecified)** +Your authentication token could not be validated, and the specific reason couldn't be determined. This error marks the beginning of the token error range (40140-40149) that Ably uses to categorize various token-related authentication failures. -The following example is a valid `extras` object: +**[40142: Token expired](/docs/platform/errors/codes/40142-token-expired)** +Your authentication token has expired and is no longer valid for accessing Ably services. - -```javascript -const extras = { - headers: { - header1: 'value1', - header2: 'value2' - } -}; -``` - +**[40144: Invalid JWT token format](/docs/platform/errors/codes/40144-invalid-jwt-token-format)** +JWT token failed validation due to missing required fields, incorrect data types, or unsupported configurations -## 40100: Unauthorized +**[40146: Unsupported token claims](/docs/platform/errors/codes/40146-unsupported-token-claims)** +Your token request includes `userClaims` or `limitsClaims`, which are not supported in Ably's server-generated tokens. -This error occurs when an action cannot be performed due to a lack of [authentication](/docs/auth). There will be additional info in the `message` property about the reason the action could not be performed. +**[40149: Token error range boundary](/docs/platform/errors/codes/40149-token-error-range-boundary)** +Authentication token encountered an issue at the boundary of Ably's token error classification range (40140-40149) -## 40101: Invalid credentials +**[40160: Insufficient capabilities](/docs/platform/errors/codes/40160-insufficient-capabilities)** +Your authentication token or API key doesn't have the required permissions to perform the requested operation on this channel. -This error occurs when [authentication](/docs/auth) credentials are invalid. The specific error message may provide further details about the cause. +**[40161: Namespace Requires Identified Clients](/docs/platform/errors/codes/40161-namespace-requires-identified-clients)** +You're trying to access a channel in a namespace that requires identified clients, but your client doesn't have a valid clientId. -An example of this error is when a signed token request is invalid due to a mismatched cryptographic signature (MAC does not match) or when the `clientId` specified in the Ably SDK does not match the `clientId` in the access token. +**[40162: Token revocation requires basic authentication](/docs/platform/errors/codes/40162-token-revocation-requires-basic-auth)** +You attempted to revoke tokens while authenticated with a token instead of an API key. Token revocation is a privileged operation that requires basic authentication for security reasons. -**Resolution:** Review your authentication setup and token request implementation. Ensure the following: +**[40164: API key missing revocable tokens attribute](/docs/platform/errors/codes/40164-api-key-missing-revocable-tokens)** +Your API key doesn't have the required `revocableTokens` attribute needed to revoke tokens. Token revocation is a privileged operation that must be explicitly enabled on API keys. -* The cryptographic signature (MAC) is correct - If a signed token request is invalid, Ably will reject it. -* The API key used to generate the token request is accurate - Double-check for missing or extra characters. -* The token request JSON is correctly formatted and unaltered, including: -** `keyName`: Must match the API key used in the request. -** `clientId`: If provided, it must match the one in the client constructor. -** `ttl`: Must be an integer in milliseconds. -** `timestamp`: Must be an integer in milliseconds. -** `capability`: Must be stringified JSON, not raw JSON. -** `nonce`: Must be a randomly generated string value. -** `mac`: Must be correctly generated using the secret key. -* The `clientId` in the SDK matches the one in the token. If a `clientId` is provided in the token, it must align with the `clientId` set in the Ably client options. -* A `clientId` cannot be changed on an existing connection. Ensure consistency in authentication. -* For JWT authentication, confirm that `clientId` is correctly set in `x-ably-clientId`. +**[40170: Authentication callback error](/docs/platform/errors/codes/40170-auth-callback-error)** +The authentication callback or authUrl failed to provide a valid token for establishing the connection. -## 40102: Incompatible credentials +**[40171: Token renewal not configured](/docs/platform/errors/codes/40171-token-renewal-not-configured)** +Your token has expired and the client cannot renew it because no renewal mechanism was configured when initializing the SDK. -This error occurs when [authentication](/docs/auth) credentials do not match the existing connection, causing the connection to enter the [failed state](/docs/connect/states). +**[40300: Forbidden](/docs/platform/errors/codes/40300-forbidden)** +Authorization error when request is understood but refused due to insufficient permissions or policy violations -Examples of this error include: +**[40331: Placement constraint environment error](/docs/platform/errors/codes/40331-placement-constraint-environment-error)** +Your app attempted to connect to an incorrect Ably environment, violating placement constraints configured for your account. -* Attempting to authenticate with an API key from a different app than the one used for the original connection -* Resuming a connection using credentials tied to a different app -* Calling `auth.authorize` with an API key that differs from the one originally used to establish the connection +**[40332: Placement Constraint Violation](/docs/platform/errors/codes/40332-placement-constraint-violation)** +Your application cannot connect to Ably because the account is restricted to a specific region or data center that doesn't match your current connection settings. -## 40103: Invalid use of Basic auth over non-TLS transport +**[40400: Resource not found](/docs/platform/errors/codes/40400-resource-not-found)** +The system could not find the resource you requested - typically an API key component, application, rule, device, or other identifier doesn't exist or is no longer available. -This error occurs when an API key is used over a non-TLS (unencrypted) connection, which is not permitted due to security risks. API keys are long-lived credentials, making them more vulnerable if exposed. Unlike short-lived tokens, API keys remain valid indefinitely, meaning a compromised key presents a significant security risk. +**[80019: Authentication provider request failed](/docs/platform/errors/codes/80019-auth-provider-request-failed)** +Your app's authentication setup failed when trying to obtain credentials from your configured auth provider (authCallback or authUrl). -Non-TLS transports can be inspected by network devices routing traffic between the client and Ably. Ably does not allow API key authentication over non-TLS connections. However, Ably supports [basic authentication](/docs/auth/basic) over TLS and [token authentication](/docs/auth/token) over non-TLS connections. +**[92002: Cipher algorithm mismatch](/docs/platform/errors/codes/92002-cipher-algorithm-mismatch)** +The encryption algorithm used to encrypt a message doesn't match the algorithm configured for decryption on this channel. -**Resolution:** Select the appropriate [authentication mechanism](/docs/auth#selecting-auth) for your use case. +**[92003: Cipher decryption failed](/docs/platform/errors/codes/92003-cipher-decryption-failed)** +The SDK was unable to decrypt an encrypted message, typically because the decryption key doesn't match the key used for encryption. -## 40104: Timestamp not current +## Connections & Transport -This error occurs when a signed token request sent to Ably is too old. Ably enforces timestamp validation to ensure [`TokenRequest`](/docs/auth/token#token-request) remain valid for a limited time, reducing the risk of interception and misuse. +**[10000: No error (operational state)](/docs/platform/errors/codes/10000-no-error-operational-state)** +A status code that indicates a successful operation or an intentional state transition, despite being labeled as an 'error' code -**Resolutions:** The following steps can help resolve this issue: -* Ensure that the authentication servers clock is accurate when generating signed token requests. -* If time synchronization is unreliable, set the `queryTime` [ClientOptions](/docs/api/rest-sdk/types#client-options) object to true when initializing the Ably client. This ensures Ably's server time is used. -* Do not cache signed token requests on the authentication server or client. Each token request must be freshly generated and used immediately. -* If using Next.js 13, prevent caching issues by setting revalidate to 0 or changing the request method from `GET` to `POST` using the `authMethod` [ClientOption](/docs/api/rest-sdk/types#client-options). +**[20000: Informational status](/docs/platform/errors/codes/20000-informational-status)** +The Ably protocol requires an ErrorInfo object for certain operations, even when nothing is wrong—this is that informational status. -## 40105: Nonce value replayed +**[40017: Unsupported protocol version](/docs/platform/errors/codes/40017-unsupported-protocol-version)** +The request did not specify a protocol version or provided an invalid version in the request parameters. -This error occurs when a signed [token request](/docs/api/realtime-sdk/types#token-request) has been used more than once. Ably enforces nonce (number used once) checks to ensure that each signed token request is unique, as a security measure. +**[40800: Request timeout](/docs/platform/errors/codes/40800-request-timeout)** +Your request to Ably didn't complete within the allowed time limit, resulting in a timeout. -Examples of this error include: -* A client sends a signed token request to Ably but does not receive the response due to network issues. If the client automatically retries the HTTP request in a fallback data center, Ably detects the duplicate nonce and rejects it. -* An authentication server caches and reuses signed token requests instead of generating a unique one for each request. -* A misconfigured [`authCallback`](/docs/auth/token#auth-callback) function reuses the same token request on every invocation instead of generating a fresh one. -* The `tokenRequest` is not renewed. A new token request should be requested from your server at this point: +**[80000: Connection failed](/docs/platform/errors/codes/80000-connection-failed)** +Your application cannot establish a connection to Ably's servers, preventing all realtime functionality from working. - -```javascript -var tokenRequest = ""; -var ably = new Ably.Realtime({ - authCallback: function(tokenParams, callback) { - // This is a mistake. The tokenRequest is not renewed. - A new token request should be requested from your server at this point */ - callback(null, tokenRequest); - } -}); -``` - +**[80002: Connection suspended](/docs/platform/errors/codes/80002-connection-suspended)** +Your connection to Ably has been suspended after network connectivity issues prevented a stable connection for more than 2 minutes. -**Resolution:** The following steps can help resolve this issue: -* Ensure that each token request is unique and never cached by the authentication server or client. -* Always generate a new token request each time authCallback is invoked. -* If retrieving a token request over HTTP, prevent caching by using the Cache-Control header (no-cache, no-store, must-revalidate) or by adding a cache-busting query string parameter, where the number is regenerated for every request, for example, `?rnd=73849275`. -* If network issues are suspected, check logs and debug the token request process to confirm proper request handling. +**[80003: Connection temporarily unavailable](/docs/platform/errors/codes/80003-connection-temporarily-unavailable)** +Your app temporarily lost its connection to Ably, which is completely normal and happens regularly in network communication. -## 40106: Unable to obtain credentials from given parameters +**[80008: Connection recovery expired](/docs/platform/errors/codes/80008-connection-recovery-expired)** +Your app attempted to resume a previous connection to Ably, but the connection had already expired (typically after 2 minutes of disconnection). -This error occurs when invalid [authentication](/docs/auth) options (key or token) are provided to the Ably SDK, preventing successful authentication. +**[80009: Connection transport unavailable](/docs/platform/errors/codes/80009-connection-transport-unavailable)** +The connection to Ably exists but the underlying network transport that carries data is missing or unavailable. -An example of this error is when no [API key](/docs/auth#api-keys) or [token](/docs/auth/token) is supplied, or when an authentication request is made using a token to request another token, instead of an API key. +**[80010: Invalid transport handle](/docs/platform/errors/codes/80010-invalid-transport-handle)** +The connection operation cannot proceed because the underlying transport handle is in an invalid or unexpected state. -## 40111: Connection limits exceeded +**[80013: Protocol Error](/docs/platform/errors/codes/80013-protocol-error)** +The communication between your application and Ably's servers encountered a protocol violation, meaning one side sent a message the other couldn't understand or process correctly. -This error occurs when the peak [connection limit](/docs/platform/pricing/limits#connection) for your account has been exceeded, preventing new connections from being established until existing ones disconnect. +**[80014: Connection timeout](/docs/platform/errors/codes/80014-connection-timeout)** +Your application couldn't establish a connection to Ably within the timeout period, similar to calling someone and waiting too long without an answer. -## 40112: Account blocked (message limits exceeded) +**[80016: Operation on Superseded Connection](/docs/platform/errors/codes/80016-operation-on-superseded-connection)** +You attempted an operation on a connection that has been replaced by a newer one, typically during a transport upgrade from HTTP to WebSocket. -This error occurs when your account has exceeded the allocated [message limit](/docs/platform/pricing/limits#message) based on your [package](/docs/pricing#packages). Once this limit is reached, further message publishing is blocked. +**[80017: Connection closed](/docs/platform/errors/codes/80017-connection-closed)** +Your connection to Ably has been closed and is no longer available for sending or receiving messages. -## 40114: Account-wide peak channel limit exceeded +**[80018: Invalid connection ID](/docs/platform/errors/codes/80018-invalid-connection-id)** +The connection ID provided to Ably doesn't match the expected format or is invalid. -This error occurs when your account has exceeded the concurrent [channel limit](/docs/platform/pricing/limits#channel), preventing additional channels from being created. +**[80023: Unable to resume connection from another site](/docs/platform/errors/codes/80023-unable-to-resume-connection)** +Your app tried to resume a connection at a different Ably data center than where it was originally established, which is not supported for consistency and performance reasons. -Examples of this error are when the application attempts to open more channels than the account allows, causing new channel creation to be blocked. Also, during development, an implementation error or bug causes unintended channel creation, leading to the limit being reached. +## Platform Infrastructure -**Resolution:** Detach unused channels to free up space for new ones. +**[10200: Unrecognized error code](/docs/platform/errors/codes/10200-unrecognized-error)** +An unrecognized error code was encountered. This error code is not currently active in Ably's systems. -## 40115: Account restricted (request limit exceeded) +**[50000: Internal server error](/docs/platform/errors/codes/50000-internal-server-error)** +An unexpected error occurred within Ably's servers while processing your request -This error occurs when your account has exceeded the allocated [limits](/docs/platform/pricing/limits) based on your [package](/docs/pricing#packages). +**[50001: Internal Channel Error](/docs/platform/errors/codes/50001-internal-channel-error)** +The channel encountered an internal error and cannot process your request. This typically indicates a temporary issue with channel operations or message processing. -## 40125: Maximum number of rules per application exceeded +**[50002: Internal connection error](/docs/platform/errors/codes/50002-internal-connection-error)** +Internal connection error preventing it from establishing or maintaining a connection to Ably's servers -This error occurs when the application has reached the maximum number of [integration rules](/docs/integrations) set by the [limits](/docs/platform/pricing/limits#app-limits) for your current package. +**[50003: Timeout error](/docs/platform/errors/codes/50003-timeout-error)** +An operation timed out before completing, typically due to network issues, temporary service unavailability, or operations exceeding configured time limits -## 40127: Maximum number of keys per application exceeded +**[50004: Service Unavailable (Capacity Limit)](/docs/platform/errors/codes/50004-service-unavailable-capacity)** +Ably's servers temporarily cannot process your request due to capacity limits or gateway timeouts -This error occurs when the application has reached the maximum number of [API keys](/docs/platform/account/app/api) set by the [limits](/docs/platform/pricing/limits#app-limits) for your current package. +**[50005: Service in lockdown](/docs/platform/errors/codes/50005-service-in-lockdown)** +Ably has temporarily placed one or more services in emergency lockdown mode to protect infrastructure during a critical incident. -## 40131: Key revoked +**[50010: Internal server error](/docs/platform/errors/codes/50010-internal-server-error)** +Ably's infrastructure encountered an internal error while processing your request. This typically occurs when edge proxy services or resource allocation systems experience unexpected issues. -This error occurs when the [Ably API key](/docs/auth#api-keys) used to initialize the SDK is no longer valid because it has been [revoked](/docs/auth/revocation) by an admin of the application. +**[50210: Bad Gateway](/docs/platform/errors/codes/50210-bad-gateway)** +Ably's edge proxy service received an invalid response from the upstream Ably platform servers when attempting to process your request. -**Resolution:** The following steps can help resolve this issue: -* If you are an admin, go to the [API keys tab](/docs/platform/account/app/api) in the Ably dashboard to check for valid keys. Use an existing valid key or create a new one with the necessary permissions. -* If you are not an admin, request a new API key from an administrator or obtain a token request generated with a valid key. +**[50300: Service Unavailable](/docs/platform/errors/codes/50300-service-unavailable)** +A required service within Ably's infrastructure is temporarily unavailable, preventing your request from being processed. -## 40133: Wrong key; cannot revoke tokens with a different key than the one that issued them +**[50310: Edge service unavailable](/docs/platform/errors/codes/50310-edge-service-unavailable)** +Ably's edge proxy service received a service unavailable response from the Ably platform backend. -This error occurs when the [Ably API key](/docs/auth#api-keys) used to authorize a token [revocation](/docs/auth/revocation) request does not match the key that originally issued the token. +**[50400: Gateway Timeout](/docs/platform/errors/codes/50400-gateway-timeout)** +An operation timed out while waiting for a response from Ably's infrastructure or while processing an asynchronous operation. -**Resolution:** The following steps can help resolve this issue: -* Ensure that the public API key ID used in the request matches the key that originally issued the token. -* Verify that the `keyname` in the request path corresponds with the API key used for authentication. +**[50410: Edge proxy gateway timeout](/docs/platform/errors/codes/50410-edge-proxy-gateway-timeout)** +Ably's edge proxy service (CloudFront) timed out waiting for a response from the Ably platform within the expected timeframe. -## 40141: Token revoked +## Chat SDK -This error occurs when attempting to authenticate with a [token](/docs/auth/token) that has been [revoked](/docs/auth/revocation) and is no longer valid. +**[42211: Message rejected by before-publish rule](/docs/platform/errors/codes/42211-message-rejected-before-publish)** +Your chat message was blocked by a custom validation rule configured for this chat room. -**Resolution:** Ensure that you are using a valid, [non-revoked](/docs/auth/revocation). token for authentication. If needed, generate a new token and use it for authorization. +**[42213: Message rejected by moderation](/docs/platform/errors/codes/42213-message-rejected-moderation)** +Your chat message was automatically blocked by AI-powered moderation because it violated the room's content policies. -## 40142: Token expired +**[102100: Room discontinuity](/docs/platform/errors/codes/102100-room-discontinuity)** +Your chat room has experienced a discontinuity that requires the application to re-synchronize its state with the server. -This error occurs when the authentication [token](/docs/auth/token#refresh) has expired and is no longer valid for use. +**[102101: Room in failed state](/docs/platform/errors/codes/102101-room-in-failed-state)** +The Chat room you're trying to use has entered a failed state and cannot perform any operations. -An example of this error is when a client attempts to authenticate with a token that has exceeded its time-to-live (TTL). +**[102102: Room is releasing](/docs/platform/errors/codes/102102-room-is-releasing)** +You attempted to perform an operation on a chat room while it's in the process of being released (cleaned up). -**Resolution:** The following steps can help resolve this issue: -* Use [`authUrl`](/docs/auth/token#auth-url) or [`authCallback`](/docs/auth/token#auth-callback) in your client configuration to enable automatic token renewal. -* If `authUrl` or `authCallback` is correctly configured, the client SDK will automatically renew the token when needed, so you may see this error temporarily before renewal occurs. +**[102103: Room is released](/docs/platform/errors/codes/102103-room-is-released)** +You attempted to perform an operation on a Chat room that has already been released and deallocated. -## 40143: Token unrecognized +**[102106: Room released before operation completed](/docs/platform/errors/codes/102106-room-released-before-operation)** +A Chat room was released while a rooms.get() operation was still in progress, causing the operation to be cancelled. -This error occurs when the provided token is not recognized as a valid Ably [token](/docs/auth/token), Ably [JWT](/docs/auth/token#jwt), or a JWT containing a valid Ably token. +**[102107: Room invalid state](/docs/platform/errors/codes/102107-room-invalid-state)** +The Chat SDK cannot perform the requested operation because the chat room is not in the correct state. -An example of this error is when a JWT is incorrectly formatted or when an Ably token does not follow the expected structure, for example: `.`. Any token that does not adhere to the correct format will not be recognized. +## Push Notifications -**Resolution:** Validate the token format before using it for authentication. If creating a [JWT](/docs/auth/token#jwt), use a standard JWT library to ensure correct generation. If using an Ably token, verify that it matches the expected format as returned from the [`requestToken`](/docs/api/token-request-spec#examples) endpoint. +**[40015: Invalid device ID](/docs/platform/errors/codes/40015-invalid-device-id)** +The device ID provided in your push notification registration request doesn't meet the required format - it must be a non-empty string. -## 40144: Unexpected error decoding JWT; decode exception +**[61002: Push activation clientId mismatch](/docs/platform/errors/codes/61002-push-activation-clientid-mismatch)** +Device was previously registered for push notifications with one user identity, but attempting to activate it with a different user identity -This error occurs when the [JWT](/docs/auth/token#jwt). provided for authentication cannot be validated by Ably due to incorrect formatting, missing claims, or unsupported configurations. +## Integrations -This error occurs when the [JWT](/docs/auth/token#jwt) provided for authentication cannot be validated by Ably. The specific reason for the failure will be available in the reason property of a [`ConnectionStateChange`](/docs/api/realtime-sdk/types#connection-state-change) object or in an error response from a REST request. +**[42922: Rate limit exceeded - too many requests](/docs/platform/errors/codes/42922-rate-limit-exceeded)** +Your application exceeded the rate limit for external service requests, causing Ably to temporarily reject your request to protect system resources and ensure fair usage. -Examples of this error include: -* Missing or invalid payload claims, such as iat (issued at) or exp (expiration). -* Using a deprecated or unsupported signing algorithm. -* Providing an empty string for `x-ably-capability`. -* Using an empty string or non-string value for [`x-ably-revocation-key`](/docs/auth/revocation#revocation-key). -* Missing kid (Key ID) when using [JWT authentication with an API key](/docs/api/realtime-sdk/authentication#ably-jwt). +**[70003: Integration max concurrency exceeded](/docs/platform/errors/codes/70003-integration-max-concurrency)** +Your Ably integration (webhooks, queues, or functions) cannot process additional messages because too many requests are already being handled concurrently. -## 40160: Action not permitted +**[70004: Integration Invalid Message Content](/docs/platform/errors/codes/70004-integration-invalid-message)** +The Ably Integration service rejected a message because its contents don't meet the requirements of the destination service (like AWS SQS, webhooks, or functions). -This error occurs when the client does not have permission to perform the requested action. +**[70005: AMQP queue timeout](/docs/platform/errors/codes/70005-amqp-queue-timeout)** +Ably couldn't deliver a message to your AMQP queue integration because the delivery operation timed out -An example of this error is when a token request includes an empty [capability object](/docs/auth/capabilities#capabilities-token), for example: `({})`, meaning the client has no assigned permissions, or when the requested [resource](/docs/auth/capabilities#wildcards) does not match the API key's allowed capabilities. +**[70006: AMQP broker backpressure](/docs/platform/errors/codes/70006-amqp-broker-backpressure)** +Your AMQP message broker (like RabbitMQ or Amazon MQ) is temporarily unable to accept new messages because it's operating at capacity. -**Resolution:** Ensure the [API key](/docs/auth#api-keys) supports the required [capabilities](/docs/auth/capabilities#capabilities-key) for the requested action. +## Asset Tracking SDK -## 40161: Access denied to channel: namespace requires identified clients +**[100000: Asset Tracking SDK error](/docs/platform/errors/codes/100000-asset-tracking-sdk-error)** +The Asset Tracking SDK encountered an internal error while processing your request. -This error occurs when a [non-identified client](/docs/auth/identified-clients) attempts to access a channel that requires an identified client. Each application's channel namespaces configuration can be found in its application settings. By default, the identified namespace requires a client to be identified. +**[100001: Invalid Asset Tracking message format](/docs/platform/errors/codes/100001-invalid-asset-tracking-message)** +The Asset Tracking SDK received a message that doesn't match the expected format for location updates. -## 40170: Error from client token callback +**[100002: Token fetch failed](/docs/platform/errors/codes/100002-token-fetch-failed)** +The Asset Tracking SDK couldn't fetch an authentication token from your token server, but will automatically retry. -This error occurs when an authentication attempt using [`authUrl`](/docs/auth/token#auth-url) or [`authCallback`](/docs/auth/token#auth-callback) fails due to a timeout, network issue, invalid token format, or another authentication error condition. +**[100003: Asset Tracking authentication failure](/docs/platform/errors/codes/100003-asset-tracking-auth-failure)** +The Asset Tracking SDK couldn't authenticate with Ably due to invalid or insufficient credentials. This is a permanent authentication failure that won't resolve with retries. -Examples of this error include when a `TokenRequest` callback times out after the default 10-second limit. Also, when he `authUrl` response is missing a Content-Type header has an unsupported Content-Type. +**[100004: Subscriber never online](/docs/platform/errors/codes/100004-subscriber-never-online)** +The Asset Tracking SDK is indicating that the subscriber has never established an initial connection to track the publisher's location. -**Resolution:** The following steps can help resolve this issue: -* Check for network latency between the client and the authentication server. -* Ensure the authentication server returns a valid Content-Type header and one of the supported content types: -** `application/json` -** `text/plain` -** `application/jwt` -* Additional error details can be found in the `error.message` field. +**[100005: Subscriber not online](/docs/platform/errors/codes/100005-subscriber-not-online)** +The Asset Tracking subscriber lost its connection to Ably after successfully establishing an initial connection, causing the publisher presence state to become unknown. -## 40171: No means provided to renew auth token +## Spaces SDK -This error occurs when no [`authUrl`](/docs/auth/token#auth-url) or [`authCallback`](/docs/auth/token#auth-callback) is provided in [`clientOptions`](/docs/getting-started/setup#options) when initializing the Ably REST or Realtime SDK. +**[101000: Space name missing](/docs/platform/errors/codes/101000-space-name-missing)** +The Ably Spaces SDK requires a valid space name but received an empty or invalid value when attempting to get or create a space. -Tokens have a set expiration time, and once expired, they are no longer valid for communication with Ably. If `authUrl` or `authCallback` is configured, the SDK will automatically request a new token before expiration, ensuring uninterrupted operation. +**[101001: Not entered space](/docs/platform/errors/codes/101001-not-entered-space)** +You attempted to perform a space operation without first entering the space. -**Resolution:** Ensure that `authUrl` or `authCallback` is set in your client configuration. This allows the SDK to automatically request a new token before the current one expires. +**[101002: Lock request already exists](/docs/platform/errors/codes/101002-lock-request-already-exists)** +You attempted to acquire a lock on a component in Ably Spaces, but there's already a pending or active lock request from your connection for the same component. -## 40300: Forbidden +**[101003: Lock is locked](/docs/platform/errors/codes/101003-lock-is-locked)** +The component lock you requested is currently held by another user, and your request did not take priority. -This error occurs when a requested action is not permitted. It serves as the default response for forbidden actions and can be triggered by various issues. - -The following are example for this error: -* Mismatched SDK versions, occurring if an application uses multiple versions of the Ably SDK, leading to inconsistencies in connections. -* A disabled account, indicating that the app belongs to an account that has been manually disabled by Ably. -* An incorrect URL for a private cluster. - -## 40311: Operation requires TLS connection - -By default, Ably apps require [TLS](/docs/platform/account/app/settings#channel-rule-configuration) for connections. This error occurs when a realtime SDK attempts to connect with TLS disabled (tls: false) while using token authentication. - -**Resolution:** The following steps can help resolve this issue: -* Ensure that the `tls` [`ClientOption`](/docs/api/realtime-sdk?#client-options) is set to true when connecting. -* If using [API key](/docs/platform/account/app/api#create) authentication, note that this scenario will result in a [`40103`](#40103) error instead. - -## 40330: Unable to activate account due to placement constraint (unspecified) - -This error occurs when an app belonging to a dedicated (private) [cluster](/docs/platform/account/enterprise-customization#dedicated-and-isolated-clusters) is accessed using an incorrect endpoint. [Enterprise](/docs/platform/pricing/enterprise) customers with private clusters receive [custom](/docs/platform/account/enterprise-customization#setting-up-a-custom-environment) environment endpoints specific to their deployment. - -An example of this error is when an app configured for a private cluster tries to connect via the default global endpoint. - -**Resolution:** Check your custom environment settings for all connecting clients to ensure they point to the correct private cluster endpoints. - -## 40331: Unable to activate account due to placement constraint (incompatible environment) - -This error occurs when an app that belongs to a dedicated (private) [cluster](/docs/platform/account/enterprise-customization#dedicated-and-isolated-clusters) is accessed using an incorrect URL. This often happens when the correct environment is not specified when initializing a client library. [Enterprise](/docs/platform/pricing/enterprise) customers with private clusters receive [custom](/docs/platform/account/enterprise-customization#setting-up-a-custom-environment) environment endpoints specific to their deployment. - -If a request arrives at an unexpected dedicated cluster or incorrect region, the account in that scope may be disabled, triggering this error. - -An example of this error is when a client intended for a dedicated environment, such as acme, connects to the default global endpoint (`realtime.ably.io`) instead of the correct dedicated cluster endpoint (`acme-realtime.ably.io`). If the expected environment is not configured, requests may be rejected. - -**Resolution:** Verify that all connecting clients are configured with the correct custom environment settings to ensure they are pointing to the intended dedicated cluster. - -## 40332: Unable to activate account due to placement constraint (incompatible site) - -This error occurs when attempting to connect to an app for an account restricted to a specific region. - -An example of this error is when a client attempts to connect to an Ably app restricted to the EU region but does not specify the EU environment in the SDK configuration. - -**Resolution:** The following steps can help resolve this issue: -* Ensure you are configured with the correct environment for your [region-restricted](https://faqs.ably.com/do-you-have-an-option-to-keep-my-data-in-europe-or-the-united-states) account. -* If your account has a regional constraint, you should have been provided with a [custom](/docs/platform/account/enterprise-customization#setting-up-a-custom-environment) environment to pass to the [`ClientOptions`](/docs/getting-started/setup#options). -* Verify that your connection settings match the region assigned to your account. - -## 40400: Not found - -This error occurs when the requested resource does not exist. This can apply to an Ably app, client, device, connection, API key, or token. The accompanying error message provides more details about the missing resource. - -Examples of this error include: -* Attempting to authenticate using an Ably API key or token, but the specified appId cannot be found. This may happen if: -** The appId is incorrect. -** The appId does not exist in the current environment (especially in a custom deployment). -* Attempting to authenticate with an incorrect API key ID, which may be due to: -* An invalid API key ID. -* The key not being found in the specified environment. -* Incorrect formatting, particularly case sensitivity issues. - -## 42910: Rate limit exceeded; request rejected - -This error occurs when a [limit](/docs/platform/pricing/limits) on your account has been reached, preventing further requests until the limit resets. The duration of the limit depends on the type of rate limit: - -* Instantaneous rate limits typically last up to six seconds before allowing message publishing to resume. -* Other limits may apply on an hourly or monthly basis. - -An example of this error is when a client exceeds the maximum allowed message rate on a channel. - -In the following example, the metric `channel.maxRate` represents the maximum rate of messages allowed to be published on a channel per second. The permitted rate is 5000 messages per second, but the client is attempting to publish 5015 messages per second, triggering the limit. - - -```text -Rate limit exceeded; request rejected (nonfatal); -metric = channel.maxRate; -interval = 2018-01-05:10:10:3; -permitted rate = 5000; -current rate = 5015; -scope = channel:[YOUR APP ID]:[YOUR CHANNEL] -(status: 429, code: 42910) (code: 42910, http status: 429) -``` - - -**Resolution:** Wait for the rate limit period to reset before retrying. Optimize your message publishing to stay within allowed limits. Upgrade your package if higher throughput is required. Review your account limits to determine which restriction has been hit. - -## 42911: Maximum account-wide instantaneous messages rate exceeded - -This error occurs when the number of [messages](/docs/platform/pricing/limits#message) sent per second exceeds the limit imposed on an account. To maintain service reliability for all users, Ably enforces usage limits at different levels, including monthly, hourly, and per-second thresholds. - -## 42912: Channel iteration call already in progress - -This error occurs when multiple concurrent [metadata REST requests](/docs/metadata-stats/metadata#rest) are made to retrieve a list of active channels. The API is rate-limited, allowing only one in-flight call at a time. Additional concurrent requests will be rejected with this error. - -**Resolution:** The following steps can help resolve this issue: -* Ensure that only one request is in progress at any given time. -* Implement request queuing or backoff strategies to avoid sending concurrent calls. -* If you require enhanced channel [enumeration capabilities](/docs/api/rest-api#enumeration-rest), visit this page to request access to the preview API. - -## 42922: Rate limit exceeded; too many requests - -This error occurs when a client has made too many requests within a 5-minute time window, causing the request to be rejected. The [limit](/docs/platform/pricing/limits#hitting) remains in effect for up to 30 seconds but may persist longer if request volume remains above the threshold from the same IP address. - -This rate limit is in place to protect the Ably platform and is not expected during normal use. - -## 50001: Internal channel error - -This error occurs when there is an internal issue on an Ably channel. - -## 50002: Internal connection error - -This error occurs when there is an internal connection issue. - -## 50003: Timeout error - -This error occurs when a [connection](/docs/connect) request to Ably times out. - -An example of this error is when a client attempts to publish a message to a channel, but the operation fails to complete within the allowed time. - -Examples of this error include: -* Poor network conditions affecting connectivity. -* Improper usage of the Ably SDKs leading to unexpected delays. -* Temporary Ably server issues impacting response times. - -## 50305: Ably's routing layer was unable to service this request - -This error occurs as a result of a request not being handled due to an internal routing error within the Ably service. - -## 61002: Activation failed: Present clientId is not compatible with existing device registration - -This error occurs when you previously [activated](/docs/push/configure/device#activate-devices) a device for push notifications with a specific `clientId`, but then changed the `clientId` used for authentication. The mismatch causes the error because the push notification setup tracks the `clientId` and other details to prevent accidental changes between app launches. The `clientId` is linked to registrations, such as subscribing by `clientId`. - -**Resolution:** If you need to change your client's `clientId`, deactivate and reactivate the device. This process triggers an internal `device.reset()` call, which clears and resets the old device details. - -## 70001: Reactor operation failed (POST operation failed) - -This error occurs when a Reactor rule fails due to an issue with the configured endpoint. Ably attempts to send a POST request, but the response is unexpected or unsuccessful. - -## 70002: Reactor operation failed (POST operation returned unexpected code) - -This error occurs when Ably sends a webhook to your server, but the server refuses or returns an unexpected response code. While Ably will retry the request multiple times, repeated failures indicate an issue on the server side. - -## 72000: Ingress operation failed - -This error occurs due to an internal error with the ingress worker. It is an unexpected issue that happens when the worker attempts to execute a rule but encounters an error during the process. - -## 72002: Ingress table is unhealthy - -This error occurs when the rule worker is unable to access or retrieve data from either the [outbox](/docs/livesync/postgres#outbox-table) or [nodes](/docs/livesync/postgres#nodes-table) table in the database as expected. - -An example of this error is misconfigurations in the database setup or inconsistencies between the provided configuration and the actual database schema or table names. - -**Resolution:** The following steps can help resolve this issue: -* Verify the configuration of the outbox and nodes tables in the database to ensure they are correctly set up and match the rule definition. -* Check for database connectivity issues and confirm that the database is accessible. -* Ensure that the schema and table names align with the expected configuration. - -## 72004: Ingress cannot identify channel, no _ablyChannel field - -This error occurs when a [MongoDB Change Stream](https://www.mongodb.com/docs/manual/changeStreams/#change-streams) event does not contain the required `_ablyChannel` field after being processed through the Change Stream pipeline. This field is essential for identifying the channel where the change event message will be published. - -**Resolution:** The following steps can help resolve this issue: -* Ensure that the `_ablyChannel` field is present at the root level of the change event. -* Avoid nesting it inside other sections, such as `$fullDocument._ablyChannel`. -* The field must be part of the main structure of the change event to allow proper identification. - -## 72005: Ingress invalid pipeline - -This error occurs when the [MongoDB Change Stream](https://www.mongodb.com/docs/manual/changeStreams/#change-streams) fails to start due to an invalid pipeline. An example of this error is when the pipeline syntax does not conform to MongoDB's requirements or contains unrecognized operators. - -**Resolution:** The following steps can help resolve this issue: -* Review the pipeline syntax for errors and ensure all operators are valid. -* Adjust the pipeline to match MongoDB's accepted structure and syntax guidelines. - -## 72006: Unable to resume from change stream - -This error occurs when the [MongoDB Change Stream](https://www.mongodb.com/docs/manual/changeStreams/#change-streams) cannot be resumed because the resume token document stored in MongoDB is not in the correct format. - -**Resolution:** The following steps can help resolve this issue: -* Verify the format of the stored resume token document in MongoDB. -* Ensure the token meets the expected structure and format required for MongoDB Change Stream resumption. -* Refer to the MongoDB documentation for guidelines on properly storing and using resume tokens. - -## 72007: Unable to store change stream resume token - -This error occurs when the [MongoDB Change Stream](https://www.mongodb.com/docs/manual/changeStreams/#change-streams) resume token cannot be stored in the `ably` collection of the database. - -**Resolution:** The following steps can help resolve this issue: -* Verify that the integration rule and MongoDB connection string are correctly configured. -* Ensure the database user has the necessary read and write permissions for the `ably` collection. -* Adjust permissions if needed to allow the token to be successfully stored. - -## 80000: Connection failed - -This error occurs when the SDK is having trouble [connecting](/docs/connect/states#connection-states) to Ably, likely due to client-side network connectivity issues. Note: The SDK will automatically retry the connection after 30 seconds. - -## 80002: Connection suspended - -This error occurs when the SDK is having trouble [connecting](/docs/connect/states#connection-states) to Ably. This is likely due to client-side network connectivity issues, and has failed to establish a connection within 2 minutes. Note: The SDK will automatically retry the connection after 15 seconds. - -## 80003: Generic disconnection error - -This error occurs when the SDK is having trouble [connecting](/docs/connect/states#connection-states) to Ably, likely due to client-side network connectivity issues. Note: The SDK will automatically retry the connection after 15 seconds. - -## 80008: Unable to recover connection (connection expired) - -This error occurs when a [connection](/docs/connect/states#connection-states) resume attempt fails because the original connection has expired. This typically happens when the [`resume`](/docs/connect/states#resume) attempt occurs after the two-minute window has passed. - -If this error occurs, the client establishes a new connection instead of resuming the old one. Any messages sent during the gap will be missed, unless channel persistence is enabled. - -**Resolution:** Ensure that resume attempts occur within the two-minute window to successfully recover a connection. If message loss is a concern, use [history](/docs/api/realtime-sdk/history) to retrieve missed messages. - -## 80014: Connection timed out - -This error occurs when a realtime [connection](/docs/connect/states#connection-states) times out after waiting for the default 10-second `realtimeRequestTimeout` in certain Ably SDKs. - -The request will be automatically retried by the SDK. - -**Resolution:** If the client never connects to the [primary or fallback endpoints](https://faqs.ably.com/routing-around-network-and-dns-issues), check any firewall rules that may be blocking access to Ably's [endpoints](https://faqs.ably.com/if-i-need-to-whitelist-ablys-servers-from-a-firewall-which-ports-ips-and/or-domains-should-i-add). - -## 80016: Operation on superseded connection - -This error occurs when a browser [connection](/docs/connect/states#connection-states) upgrades from an HTTP (Comet) transport to WebSockets. It is logged by the client library when operations are performed on the older transport. - -**Resolution:** the following steps can help resolve this issue: -* If this error only appears in logs, it is harmless and does not affect your application. No action is needed. -* If you receive this error as a response to a request, contact Ably support with relevant logs and details, and they will investigate the issue. - -## 80017: Connection closed - -This error occurs when a [connection](/docs/connect/states#connection-states) has been closed and an operation is attempted on it, such as calling a channel or presence method, for example, `channel.presence.update` while the connection is still in a closed state. - -**Resolution:** The following steps can help resolve this issue: -* Check the client's connection state before performing operations to ensure the connection is active. -* If the connection is closed, reconnect before making requests to avoid this error. - -## 80018: Invalid connection ID (invalid format) - -This error occurs when an invalid `connectionId` is supplied. - -**Resolution:** If you are seeing resumes failing in ably-js, this was a known bug in ably-js versions 1.2.30 through 1.2.33. Upgrading to the latest version of ably-js should resolve the issue. - -## 80019: Auth server rejecting request - -This error occurs when the client library fails to obtain a token using the client-supplied [`authUrl`](/docs/auth/token#auth-url) or [`authCallback`](/docs/auth/token#auth-callback). It is raised when the request to the authentication server fails due to an error or exception in the callback. - -## 80020: Continuity loss due to maximum subscribe message rate exceeded - -This error occurs when a client exceeds the [outbound](/docs/platform/pricing/limits#connection) subscribe message rate on a realtime connection. - -**Resolution:** The subscriber will receive an `UPDATE` [channel state change](/docs/api/realtime-sdk/channels#channel-state-change) event, indicating that continuity is lost. Use the [`resume`](/docs/connect/states#resume) flag to determine whether to recover missing messages or handle the failure accordingly. - -## 80021: Max new connections rate exceeded - -This error occurs when the maximum allowed rate of new connections for an account has been [exceeded](/docs/platform/pricing/limits#hitting). - -## 80022: Unable to find connection - -This error can occur when using the Comet transport, where a `send` or `recv` request is sent to the system but reaches a different frontend instance than the one hosting the connection. This can happen due to a disruption on a frontend instance. - -**Resolution:** This is a non-fatal error, and no action is required. The transport will automatically drop and be re-initiated without any need for manual intervention. - -## 80023: Unable to resume connection from a different site - -This error occurs when a disconnected client attempts to resume a [connection](/docs/connect) from a different site than the original connection. This typically happens when a client tries to [`resume`](/docs/connect/states#resume) via a fallback host. - -**Resolution:** Channel message continuity will not be possible in this scenario. Any messages sent while the client was disconnected will need to be retrieved using [history](/docs/storage-history/history). - -## 90001: Channel operation failed (invalid channel state) - -This error occurs when an application attempts to perform an operation on a channel that is in a [state](/docs/channels/states#connection-state) that does not permit it. - -An example of this error is when an application tries to [publish](/docs/pub-sub#publish) a message or attach to a channel that is in a failed state due to a prior error. As a result, the operation fails because actions cannot be performed on a channel in this state. - -**Resolution:** The following steps can help resolve this issue: -* Ensure the channel is in an appropriate state before performing any operations. -* Use an Ably SDK to listen for channel state changes and handle operations accordingly. -* Implement state change callbacks to trigger the intended operation when the channel is in a valid [state](/docs/channels/states). - -## 90004: Unable to recover channel (message limit exceeded) - -This error occurs when using the rewind feature with a specified time period, and the total number of messages within the selected timeframe exceeds the maximum [limit](/docs/channels/options/rewind#limits) that can be retrieved in a single request. - -## 90007: Channel didn't attach within 00:00:10 - -This error occurs when a channel fails to [attach](/docs/channels/states#attach) within the default 10-second timeout. It is most commonly encountered by clients with poor internet connections, where the `ACK` response to an `ATTACH` request does not return within the expected timeframe. - -Note: In older versions of the ably-java SDK, this error was incorrectly assigned to error code `91200`. - -**Resolution:** Adjust the `realtimeRequestTimeout` or `channelRetryTimeout` (depending on the SDK) to a higher value to allow more time for the attachment process. - -## 90010: Maximum number of channels per connection exceeded - -This error occurs when a Realtime client [attaches](/docs/channels/states#attach) to more channels than the account allows on a single connection. This happens when channels are attached but never explicitly detached, causing the limit to be reached. - -**Resolution:** Review your channel [limits](/docs/platform/pricing/limits#channel) and ensure that channels are explicitly detached when no longer needed. - -## 90021: Max channel creation rate exceeded - -This error occurs when the [maximum](/docs/platform/pricing/limits#channel) rate of channel creation has been exceeded, across an account. Until the rate returns below the limit, new channels may not be created immediately. The Ably SDK will automatically retry every 10 seconds until the request succeeds. - -## 91000: Unable to enter presence channel (no clientId) - -This error occurs when a client attempts to [enter](/docs/chat/rooms/presence#set) the [presence](/docs/presence-occupancy/presence) set of a channel without specifying a `clientId`. - -A client can be identified in several ways: -* If using [token](/docs/auth/token) authentication, ensure the token is associated with a `clientId` by setting the `clientId` field in `tokenParams` when creating a token request or requesting a token. -* If using basic authentication or token authentication with a wildcard `clientId`, set the `clientId` in the client options when initializing the Ably SDK. -* Specify a `clientId` at the time of entering presence using [`enterClient()`](/docs/api/realtime-sdk/presence#enterclient). - -## 91003: Maximum member limit exceeded - -This error occurs when the [maximum](/docs/platform/pricing/limits#hitting) number of clients in the [presence](/docs/presence-occupancy/presence) set for a channel has been reached, preventing additional clients from joining. - -## 91005: Presence state is out of sync - -This is a client-side issue that occurs when an up-to-date [presence](/docs/presence-occupancy/presence) set cannot be retrieved due to connection issues. It typically happens when calling `presence.get()` while the channel is in a suspended state, often caused by an interruption in the client's internet connection. - -**Resolution:** The following steps can help resolve this issue: -* Ensure the client has an active connection before calling `presence.get()`. -* If an outdated presence set is acceptable, set `waitForSync` to `false` to retrieve the presence data even when out of sync. - -## 92000: Invalid object message - -This error occurs when an object message used to represent [operations](/docs/liveobjects/concepts/operations) and [objects](/docs/liveobjects/concepts/objects) is malformed or contains invalid data that cannot be processed. - -* If this error occurs when using the REST API, the error response will include additional details about how to correctly construct your request. -* If this error occurs when using a Realtime SDK, it likely indicates a bug in the client. Please raise an issue in the GitHub repository for the SDK you are using with relevant logs and details. - -## 92001: Objects limit exceeded - -This error occurs when the maximum number of [objects](/docs/liveobjects) on the channel has exceeded the allowed [limit](/docs/platform/pricing/limits#channel) for the account or application. - -**Resolution:** -* Remove any unnecessary objects from the channel to free up space, for example by [removing](/docs/liveobjects/map#remove) any references to them. -* [Upgrade](/docs/pricing) your package to increase the [limit](/docs/platform/pricing/limits#channel) on the allowed number of objects on the channel. - -## 92002: Unable to submit operation on tombstone object - -This error occurs when attempting to perform an [operation](/docs/liveobjects/concepts/operations) on a [tombstone](/docs/liveobjects/concepts/objects#tombstones) object (an object that has been marked as deleted). - -**Resolution:** -* Retry the operation on an object that is not a tombstone and is [reachable](/docs/liveobjects/concepts/objects#reachability) from the [root object](/docs/liveobjects/concepts/objects#root-object) . - -## 92003: Unable to fetch object tree with tombstone object as root - -This error occurs when attempting to fetch an [object](/docs/liveobjects/concepts/objects) tree where the specified object is a [tombstone](/docs/liveobjects/concepts/objects#tombstones) object (an object that has been marked as deleted). - -You may encounter this error when [fetching objects](/docs/liveobjects/rest-api-usage#fetching-objects-get-children) via the REST API using the `children` query parameter, or if using the [compact](/docs/liveobjects/rest-api-usage#fetching-objects-compact) endpoint. - -**Resolution:** -* Retry the operation on an object that is not a tombstone and is [reachable](/docs/liveobjects/concepts/objects#reachability) from the [root object](/docs/liveobjects/concepts/objects#root-object) . - -## 92004: Object not found - -This error occurs when attempting to access an [object](/docs/liveobjects/concepts/objects) that does not exist. - -You may encounter this error when using the [REST API](/docs/liveobjects/rest-api-usage) or if calling methods on a [LiveMap](/docs/liveobjects/map) or [LiveCounter](/docs/liveobjects/map) instance that has been deleted. - -**Resolution:** -* Listen for [lifecycle events](/docs/liveobjects/lifecycle) on object instances to be notified when an object is deleted. -* Retry the REST API request with a valid [object ID](/docs/liveobjects/rest-api-usage#updating-objects-by-id) or [path](/docs/liveobjects/rest-api-usage#updating-objects-by-path) that corresponds to an existing object. - -## 92005: No objects found matching operation path - -This error occurs when no objects are found that match the specified [path](/docs/liveobjects/rest-api-usage#updating-objects-by-path) when using the REST API. - -**Resolution:** -* Ensure that the `path` is correctly specified and corresponds to an existing object. - -## 92006: Unable to perform operation without objectId or path - -This error occurs when attempting to perform an operation without providing either an [object ID](/docs/liveobjects/rest-api-usage#updating-objects-by-id) or [path](/docs/liveobjects/rest-api-usage#updating-objects-by-path) to identify the target object when using the REST API. - -**Resolution:** -* Ensure that the request includes either an `objectId` or a `path` parameter to specify the target object for the operation. - -## 92007: Operation not processable on path - -This error occurs when the requested operation cannot be processed for the object located at the specified [path](/docs/liveobjects/rest-api-usage#updating-objects-by-path) when using the REST API. - -You may encounter this error when the type of the object located at the specified path does not support the specified operation (e.g. publishing a `COUNTER_INC` operation on a [LiveMap](/docs/liveobjects/map) instance). - -**Resolution:** -* Ensure that the operation is valid for the type of object at the specified path. - -## 101000: Space name missing - -This error occurs when calling [`spaces.get()`](/docs/spaces/space#options) without specifying a space name. The name parameter is required to retrieve a space. - -**Resolution:** Ensure that a valid space name is provided when calling `spaces.get()`: - - -```javascript -const space = await spaces.get('mySpaceName'); -``` - - -## 101001: Not entered space - -This error occurs when calling a function that requires the client to be [entered](/docs/spaces/space#enter) into a space, but the client has not yet done so. - -**Resolution:** Ensure that `space.enter()` is called before performing operations that require the client to be inside the space: - - -```javascript -const space = await spaces.get('mySpace'); -space.enter({ - username: 'Claire Lemons', - avatar: 'https://slides-internal.com/users/clemons.png', -}); -``` - - -## 101002: Lock request exists - -This error occurs when an existing [lock request](/docs/spaces/locking#states) is still pending or locked. Nested locks are not supported, so a new lock cannot be requested until the previous one is resolved. - -## 101003: Lock is locked - -This error occurs when a lock is already in the [locked state](/docs/spaces/locking#states), and a pending request did not override or release the lock. - -## 101004: Lock invalidated - -This error occurs when a [lock request](/docs/spaces/locking#states) invalidates an existing lock that was already in the locked state. +**[101004: Lock invalidated](/docs/platform/errors/codes/101004-lock-invalidated)** +Your lock request on a Spaces component was invalidated by another member's lock request that had higher priority. \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/101000-space-name-missing.mdx b/src/pages/docs/platform/errors/codes/101000-space-name-missing.mdx index 2d56debc15..83a1633d90 100644 --- a/src/pages/docs/platform/errors/codes/101000-space-name-missing.mdx +++ b/src/pages/docs/platform/errors/codes/101000-space-name-missing.mdx @@ -1,13 +1,13 @@ - + - + # Error 101000: Space name missing @@ -38,113 +38,204 @@ You'll see this message: 1. **Empty string passed** (40% of cases) - Passing an empty string `""` to `spaces.get()` - Accidentally clearing a variable before use - + - String trimming resulting in empty value + 2. **Null or undefined value** (35% of cases) - Variable not initialized before use - Missing parameter in function call - Async data not loaded yet - + - Destructuring from undefined object + 3. **Wrong parameter type** (25% of cases) - Passing a number instead of a string - Passing an object or array - Type conversion issues - + - Template literal evaluation errors + ## Resolution Steps 1. **Check your space name parameter** ```javascript // ❌ Wrong: These will trigger error 101000 - await spaces.get(""); // Empty string - await spaces.get(null); // Null value - await spaces.get(undefined); // Undefined - await spaces.get(123); // Number instead of string - await spaces.get({name: "room"}); // Object instead of string + await spaces.get(""); // Empty string + await spaces.get(null); // Null value + await spaces.get(undefined); // Undefined + await spaces.get(123); // Number instead of string + await spaces.get({name: "room"}); // Object instead of string // ✅ Correct: Use a non-empty string await spaces.get("my-space"); await spaces.get("room-123"); await spaces.get("chat-" + userId); + await spaces.get(`user-${userId}-space`); ``` - + 2. **Validate input before calling** ```javascript // Add validation before using the Spaces SDK function getSpace(spaceName) { + // Type and emptiness check if (typeof spaceName !== 'string' || spaceName.length === 0) { throw new Error('Space name must be a non-empty string'); } - return spaces.get(spaceName); + + // Optional: Additional validation + const trimmed = spaceName.trim(); + if (trimmed.length === 0) { + throw new Error('Space name cannot be only whitespace'); + } + + return spaces.get(trimmed); } ``` - + 3. **Handle dynamic space names** ```javascript // When using dynamic names, ensure they're valid - const roomId = getRoomId(); // Could return null/undefined + const roomId = await getRoomId(); // Could return null/undefined // ❌ Wrong: Direct use without validation const space = await spaces.get(roomId); // ✅ Correct: Validate first - if (roomId && typeof roomId === 'string') { - const space = await spaces.get(roomId); + if (roomId && typeof roomId === 'string' && roomId.trim()) { + const space = await spaces.get(roomId.trim()); } else { console.error('Invalid room ID:', roomId); + // Handle the error appropriately for your application } ``` - + + +4. **TypeScript for compile-time safety** + ```typescript + // TypeScript will catch type errors at compile time + interface SpaceConfig { + name: string; + metadata?: Record; + } + + async function createSpace(config: SpaceConfig): Promise { + // TypeScript ensures config.name is a string + if (!config.name || config.name.trim().length === 0) { + throw new Error('Space name cannot be empty'); + } + return await spaces.get(config.name); + } + ``` + ## Automatic Handling This is a validation error that occurs synchronously when you call `spaces.get()`. It will not be automatically retried as it indicates an issue with your code that must be fixed. -## Prevention - -- **Always validate user input**: If space names come from user input, validate them before passing to the SDK -- **Use TypeScript**: TypeScript will catch type mismatches at compile time -- **Set default values**: Provide fallback values for optional parameters -- **Test edge cases**: Include tests for empty strings, null, and undefined values +## Code Examples +### Complete Implementation with Error Handling ```javascript -// Example with proper validation +import Spaces from '@ably/spaces'; +import { Realtime } from 'ably'; + +// Initialize Spaces +const client = new Realtime({ key: 'your-api-key' }); +const spaces = new Spaces(client); + +// Robust space management class class SpaceManager { constructor(spaces) { this.spaces = spaces; + this.spaceCache = new Map(); } async getOrCreateSpace(name) { - // Validate input - if (!name || typeof name !== 'string' || name.trim().length === 0) { - throw new Error(`Invalid space name: ${name}`); + // Comprehensive validation + if (name === null || name === undefined) { + throw new Error('Space name is required'); } - // Sanitize the name - const sanitizedName = name.trim(); + if (typeof name !== 'string') { + throw new Error(`Space name must be a string, got ${typeof name}`); + } + + const trimmedName = name.trim(); + if (trimmedName.length === 0) { + throw new Error('Space name cannot be empty or whitespace'); + } + + // Check cache first + if (this.spaceCache.has(trimmedName)) { + return this.spaceCache.get(trimmedName); + } try { - return await this.spaces.get(sanitizedName); + const space = await this.spaces.get(trimmedName); + this.spaceCache.set(trimmedName, space); + return space; } catch (error) { if (error.code === 101000) { - console.error('Space name validation failed:', error.message); - // Handle the error appropriately + // This shouldn't happen after our validation + console.error('Unexpected validation error:', error.message); } throw error; } } } + +// Usage +const manager = new SpaceManager(spaces); + +// Safe usage with error handling +try { + const space = await manager.getOrCreateSpace('collaborative-doc-123'); + await space.enter({ name: 'User' }); +} catch (error) { + console.error('Failed to join space:', error); +} ``` - + + +## Prevention + +- **Always validate user input**: If space names come from user input, validate them before passing to the SDK +- **Use TypeScript**: TypeScript will catch type mismatches at compile time, preventing runtime errors +- **Set default values**: Provide fallback values for optional parameters +- **Test edge cases**: Include tests for empty strings, null, and undefined values +- **Implement wrapper functions**: Create validated wrapper functions around SDK calls +- **Document expectations**: Clearly document that space names must be non-empty strings + +## Performance Impact + +This error has minimal performance impact as it: +- Fails immediately without any network calls +- Occurs synchronously during validation +- Doesn't affect other spaces or connections +- Requires only a parameter fix to resolve + +## Related Errors + +• **[101001 - Not Entered Space](https://help.ably.io/error/101001)** + Occurs when attempting operations on a space before entering it + +• **[101002 - Lock Request Already Exists](https://help.ably.io/error/101002)** + Related validation error for duplicate lock requests + +• **[101003 - Lock Is Currently Locked](https://help.ably.io/error/101003)** + Validation error when attempting to acquire an already-locked resource + +• **[101004 - Lock Request Invalidated](https://help.ably.io/error/101004)** + Occurs when a lock request becomes invalid due to concurrent operations ## Related Resources -- [Ably Spaces documentation](https://ably.com/docs/spaces) +- [Ably Spaces documentation](https://ably.com/docs/products/spaces) - [Spaces SDK GitHub repository](https://github.com/ably/spaces) -- [Getting started with Spaces](https://ably.com/docs/spaces/get-started) +- [Spaces SDK npm package](https://www.npmjs.com/package/@ably/spaces) +- [Ably documentation](https://ably.com/docs) ## Need Further Help? @@ -165,11 +256,14 @@ Our team will help you resolve this issue as quickly as possible. - + + + @@ -206,6 +305,6 @@ To improve this error code documentation: 1. First approach: Update editorial-notes.md in ably-os repository with specific guidance for error 101000 2. Regenerate: Run `./bin/ably-os errors document-error-codes 101000 --force` 3. For broader improvements: Review and update ably-os prompt templates -4. Context: See https://github.com/ably/ably-os/blob/main/docs/ERROR_COMMANDS_GUIDE.md +4. Context: See https://github.com/ably/ably-os/blob/bfa911b/docs/ERROR_COMMANDS_GUIDE.md 5. Source repository: https://github.com/ably/ably-os --> \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/101001-not-entered-space.mdx b/src/pages/docs/platform/errors/codes/101001-not-entered-space.mdx index 8f2314a84b..b073857c7e 100644 --- a/src/pages/docs/platform/errors/codes/101001-not-entered-space.mdx +++ b/src/pages/docs/platform/errors/codes/101001-not-entered-space.mdx @@ -1,11 +1,11 @@ - + @@ -38,17 +38,17 @@ You'll see this message: 1. **Not calling space.enter()** (90% of cases) - Attempting operations immediately after getting a space reference - Forgetting to enter the space in your initialization code - + 2. **Race conditions** (8% of cases) - Calling space operations before `enter()` completes - Not awaiting the enter operation - + 3. **Wrong space instance** (2% of cases) - Operating on a different space than the one entered - Creating multiple space instances accidentally - + ## Resolution Steps @@ -65,7 +65,7 @@ You'll see this message: // Now you can perform operations await space.cursors.set({ position: { x: 50, y: 50 } }); ``` - + 2. **Verify you've entered the space** ```javascript @@ -75,7 +75,7 @@ You'll see this message: await space.enter({ username: 'User Name' }); } ``` - + 3. **Handle the error gracefully** ```javascript @@ -92,12 +92,12 @@ You'll see this message: } } ``` - + ## Automatic Handling The Spaces SDK does not automatically enter spaces. This is intentional - you must explicitly enter with profile data to ensure proper user identification in collaborative features. - + ## Code Examples @@ -118,7 +118,7 @@ await space.enter({ await space.locations.set({ x: 100, y: 200 }); await space.cursors.set({ position: { x: 50, y: 50 } }); ``` - + ### Operations That Require Entry @@ -127,7 +127,7 @@ The following operations will throw error 101001 if you haven't entered the spac - **Space membership**: `space.leave()` - **Cursor management**: `cursors.set()` - **Location tracking**: `locations.set()` - + ## Prevention @@ -135,13 +135,23 @@ The following operations will throw error 101001 if you haven't entered the spac - Use async/await to ensure enter completes before other operations - Store the space instance to avoid creating duplicates - Include proper error handling for space operations - + ## Related Resources - [Spaces documentation](https://ably.com/docs/spaces/space#enter) - [Space.enter() API reference](https://ably.com/docs/spaces/space#enter) -- Related errors: [101000](https://help.ably.io/error/101000), [101002](https://help.ably.io/error/101002), [101003](https://help.ably.io/error/101003) + +## Related Errors + +• **[101000 - Space name missing](https://help.ably.io/error/101000)** + Occurs when calling `spaces.get()` without providing a space name parameter + +• **[101002 - Lock request already exists](https://help.ably.io/error/101002)** + Indicates an existing lock request in pending or locked state - nested locks are not supported + +• **[101003 - Lock is currently locked](https://help.ably.io/error/101003)** + The lock is in locked state and the pending request did not invalidate the status ## Need Further Help? @@ -163,33 +173,36 @@ Our team will help you resolve this issue as quickly as possible. + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/101002-lock-request-already-exists.mdx b/src/pages/docs/platform/errors/codes/101002-lock-request-already-exists.mdx index 74d8ce88be..1b7b09d7d1 100644 --- a/src/pages/docs/platform/errors/codes/101002-lock-request-already-exists.mdx +++ b/src/pages/docs/platform/errors/codes/101002-lock-request-already-exists.mdx @@ -1,13 +1,13 @@ - + - + # Error 101002: Lock request already exists @@ -39,13 +39,13 @@ You'll see this exact message: - Calling `acquire()` multiple times without waiting for the first to complete - Attempting to acquire a lock that's already pending or locked by your connection - Race conditions in application code triggering duplicate lock requests - + 2. **Missing lock state management** (10% of cases) - Not tracking lock status in your application - Ignoring lock state change events - Not properly handling lock lifecycle - + ## Resolution Steps @@ -60,15 +60,15 @@ You'll see this exact message: console.log('Lock already exists, waiting...'); } ``` - + 2. **Handle existing lock appropriately** - If `status === 'pending'`: Wait for the lock request to complete - If `status === 'locked'`: Either use the existing lock or release it first - If `status === 'unlocked'`: Safe to acquire a new lock - + -3. **Implement proper lock lifecycle management** +3. **Implement proper lock lifecycle management with React hooks** ```javascript // React example with proper lock handling const { status, member, acquire, release } = useLock('component-id'); @@ -79,33 +79,49 @@ You'll see this exact message: try { const lock = await acquire(); // Lock acquired successfully + console.log('Lock acquired'); } catch (error) { if (error.code === 101002) { console.log('Lock request already exists'); - // Handle appropriately + // Handle appropriately - wait for existing request } } + } else { + console.log(`Cannot acquire - lock status is: ${status}`); } }; ``` - + 4. **Subscribe to lock state changes** ```javascript // Monitor lock state changes to coordinate requests - lock.subscribe((update) => { - console.log(`Lock status changed to: ${update.status}`); - if (update.status === 'unlocked') { + lock.subscribe('update', (lockUpdate) => { + console.log(`Lock status changed to: ${lockUpdate.status}`); + if (lockUpdate.status === 'unlocked') { // Now safe to acquire if needed } }); ``` - + + +5. **Use attributes for better lock management** + ```javascript + // Include metadata when acquiring locks + const lock = await acquire({ + attributes: { + componentId: 'editor-field-1', + userId: currentUser.id, + timestamp: Date.now() + } + }); + ``` + ## Automatic Handling The Ably Spaces SDK does not automatically retry lock acquisitions for this error. Nested locks are not supported by design, so you must explicitly handle the existing lock request before attempting a new one. - + ## Prevention @@ -114,14 +130,30 @@ The Ably Spaces SDK does not automatically retry lock acquisitions for this erro - **Use lock events** to coordinate multiple lock requests - **Release locks promptly** when no longer needed to avoid conflicts - **Avoid duplicate calls** to `acquire()` in event handlers or loops - +- **Implement debouncing** for user-triggered lock requests +- **Use React hooks properly** to manage lock state in components + + +## Related Errors + +• **[101000 - Space Name Missing](https://help.ably.io/error/101000)** + Invalid or missing space name when creating a space instance + +• **[101001 - Not Entered Space](https://help.ably.io/error/101001)** + Must enter the space before attempting to acquire locks + +• **[101003 - Lock is Locked](https://help.ably.io/error/101003)** + Lock is already held by another member - occurs when trying to acquire a lock held by someone else + +• **[101004 - Lock Invalidated](https://help.ably.io/error/101004)** + Your lock request was invalidated by another member's acquisition ## Related Resources - [Ably Spaces Locking Documentation](https://ably.com/docs/spaces/locking) - [Component Locking States](https://ably.com/docs/spaces/locking#states) - [Spaces React Hooks](https://ably.com/docs/spaces/react) -- Related errors: [101001](https://help.ably.io/error/101001) (Not entered space), [101003](https://help.ably.io/error/101003) (Lock is locked by another member) +- [Interactive Locking Example](https://ably.com/examples/spaces-component-locking) ## Need Further Help? @@ -142,49 +174,47 @@ Our team will help you resolve this issue as quickly as possible. - - + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/101003-lock-is-locked.mdx b/src/pages/docs/platform/errors/codes/101003-lock-is-locked.mdx index cc88524c4d..ef16ef5913 100644 --- a/src/pages/docs/platform/errors/codes/101003-lock-is-locked.mdx +++ b/src/pages/docs/platform/errors/codes/101003-lock-is-locked.mdx @@ -1,13 +1,13 @@ - + - + # Error 101003: Lock is locked @@ -29,51 +29,81 @@ The component lock you requested is currently held by another user, and your req You'll see this in the lock response: - "lock is currently locked" +The error is assigned to the `reason` property when lock acquisition fails. + ## Common Causes 1. **Concurrent lock attempts** (Most common) - Multiple users trying to edit the same component simultaneously - Normal behavior in collaborative applications - + - Part of the distributed locking mechanism design + -2. **Network timing** - - Lock requests arriving out of order +2. **Network timing and race conditions** + - Lock requests arriving out of order due to network latency - Presence system delays affecting lock state synchronization - + - Temporary network disconnections causing lock state mismatches + + +3. **Priority resolution conflicts** + - Timestamp-based priority system determines lock ownership + - Connection ID used as tiebreaker when timestamps match + - Existing lock holder maintains priority over new requests + ## Resolution Steps 1. **Handle as expected behavior** - This is not an error but normal lock contention - Design your UI to gracefully handle locked components - + - Show visual feedback about who holds the lock + -2. **Subscribe to lock updates** +2. **Subscribe to lock update events** - Monitor when the lock becomes available - Automatically retry when the lock is released - + - Implement a subscription before attempting lock acquisition + -3. **Implement visual feedback** +3. **Implement proper retry strategy** + - Use exponential backoff with jitter for retries + - Set a maximum retry limit to prevent infinite loops + - Consider offering manual retry option to users + + +4. **Provide comprehensive visual feedback** - Show who currently holds the lock - Display queue position if applicable - Notify users when locks become available - + - Consider showing estimated wait time + ## Automatic Handling -The Spaces SDK does not automatically retry lock acquisition. Your application should implement appropriate retry logic based on your use case. - +The Spaces SDK does not automatically retry lock acquisition. Your application must implement appropriate retry logic based on your specific use case and user experience requirements. + ## Prevention - Consider using optimistic UI updates where appropriate - Design your collaborative features to minimize lock contention - Implement clear visual indicators of component availability - +- Use granular locking (lock smaller components when possible) +- Consider read-only modes for viewing without locking + ## Related Resources - [Ably Spaces Component Locking documentation](https://ably.com/docs/spaces/locking) - [Ably Spaces SDK documentation](https://ably.com/docs/spaces) -- Related errors: None (this is a Spaces-specific lock contention indicator) - + +## Related Errors + +• **[101000 - Lock Invalid Request](https://help.ably.io/error/101000)** + Invalid lock request parameters or configuration issues + +• **[101001 - Lock Request Exists](https://help.ably.io/error/101001)** + Duplicate lock request already pending for the same component + +• **[101002 - Lock Invalidated](https://help.ably.io/error/101002)** + Lock was invalidated by another request with higher priority ## Need Further Help? @@ -94,33 +124,40 @@ Our team will help you resolve this issue as quickly as possible. - + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/101004-lock-invalidated.mdx b/src/pages/docs/platform/errors/codes/101004-lock-invalidated.mdx index 85c8c938f3..a107a79d07 100644 --- a/src/pages/docs/platform/errors/codes/101004-lock-invalidated.mdx +++ b/src/pages/docs/platform/errors/codes/101004-lock-invalidated.mdx @@ -1,20 +1,21 @@ - + - + # Error 101004: Lock invalidated ## What Happened -Your lock request on a Spaces component was invalidated by another member's lock request that had higher priority. +Your lock request on a Spaces component was invalidated by another member's lock request that had higher priority based on timestamp and connection ID. ## Quick Reference @@ -33,22 +34,26 @@ Your lock request on a Spaces component was invalidated by another member's lock You'll see this in the lock's `reason` property when it transitions to `unlocked`: - "lock was invalidated by a concurrent lock request which now holds the lock" - "Lock invalidated" +- "The lock request invalidated an existing lock in the locked state" ## Common Causes 1. **Concurrent lock requests** (90% of cases) - Multiple members attempting to lock the same component simultaneously - The member with the earlier timestamp gets priority - + - When timestamps are identical, lower connection ID wins + 2. **Network latency differences** (8% of cases) - Members with better network conditions may submit requests with earlier timestamps - Slight timing differences can affect lock priority + - Clock synchronization variations between clients 3. **Component lifecycle issues** (2% of cases) - React components not properly cleaning up lock subscriptions - Lock events firing after component unmounting - + - Missing cleanup in useEffect return functions + ## Resolution Steps @@ -57,16 +62,18 @@ You'll see this in the lock's `reason` property when it transitions to `unlocked space.locks.subscribe('update', (lock) => { if (lock.reason?.code === 101004) { // Your lock was invalidated + console.log('Lock invalidated by another member'); handleLockInvalidation(lock); } }); ``` - + 2. **Implement graceful handling** - Notify the user that another member has taken control - Update your UI to reflect the locked state - Consider implementing a queue or retry mechanism + - Show who currently holds the lock if available 3. **For React applications: Ensure proper cleanup** ```javascript @@ -79,21 +86,23 @@ You'll see this in the lock's `reason` property when it transitions to `unlocked }; }, []); ``` - + 4. **Understanding lock priority** - - Earlier timestamps always win + - Earlier timestamps always win in conflict resolution - When timestamps are identical, lower connection IDs win - This ensures deterministic conflict resolution across all clients - + - The algorithm guarantees consistent results regardless of network conditions + ## Automatic Handling -Unlike thrown exceptions, error 101004 is assigned to the lock's `reason` property when invalidated. This allows your application to: +Unlike thrown exceptions, error 101004 is assigned to the lock's `reason` property when invalidated. This design choice allows your application to: - Continue running without exception handling - React to lock state changes through event subscriptions - Handle invalidation gracefully without disrupting user experience - +- Maintain application state consistency during conflicts + ## Code Examples @@ -103,17 +112,17 @@ Unlike thrown exceptions, error 101004 is assigned to the lock's `reason` proper // Initialize Spaces const space = await spaces.get('collaborative-doc'); -// Request a lock with invalidation handling +// Request a lock with comprehensive invalidation handling async function acquireLockWithHandling(componentId) { try { // Subscribe to lock updates before acquiring const subscription = space.locks.subscribe('update', (lock) => { if (lock.id === componentId && lock.reason?.code === 101004) { - // Lock was invalidated + // Lock was invalidated by higher priority request console.log('Lock invalidated by another member'); - updateUIForLockedState(); + updateUIForLockedState(lock.member); - // Optional: Retry after delay + // Optional: Implement retry with backoff setTimeout(() => retryLockAcquisition(componentId), 2000); } }); @@ -138,21 +147,83 @@ function releaseLock(lock, subscription) { return lock.release(); } ``` - + + +### React Hook Pattern for Lock Management + +```javascript +function useComponentLock(componentId) { + const [lockStatus, setLockStatus] = useState('unlocked'); + const [lockHolder, setLockHolder] = useState(null); + + useEffect(() => { + let subscription; + + async function setupLock() { + subscription = space.locks.subscribe('update', (lock) => { + if (lock.id === componentId) { + setLockStatus(lock.status); + setLockHolder(lock.member); + + if (lock.reason?.code === 101004) { + // Handle invalidation in UI + showNotification('Your edit access was transferred to another user'); + } + } + }); + } + + setupLock(); + + // Critical: Clean up subscription on unmount + return () => { + if (subscription) { + subscription.unsubscribe(); + } + }; + }, [componentId]); + + return { lockStatus, lockHolder }; +} +``` + ## Prevention -- Implement visual indicators showing when components are locked -- Use optimistic UI updates with rollback capabilities -- Consider implementing a queue system for lock requests +- Implement visual indicators showing when components are locked or being edited +- Use optimistic UI updates with rollback capabilities for better user experience +- Consider implementing a queue system for lock requests in high-contention scenarios - In React apps, always clean up lock subscriptions in useEffect cleanup functions +- Add user notifications when locks are acquired or lost + +## Performance Impact + +Lock invalidation has minimal performance impact: +- No network round-trip required for invalidation detection +- Event-driven updates ensure immediate notification +- Optimistic locking reduces perceived latency to ~100ms +- Priority algorithm executes locally without server validation ## Related Resources - [Spaces Locking Documentation](https://ably.com/docs/spaces/locking) - [Spaces React Hooks](https://ably.com/docs/spaces/react) - [Component Locking Guide](https://ably.com/docs/spaces/locking#handling-lock-conflicts) -- Related errors: [101002](https://help.ably.io/error/101002) (lock already held), [101003](https://help.ably.io/error/101003) (lock released) +- [Spaces SDK Reference](https://ably.com/docs/spaces) + +## Related Errors + +• **[101002 - Lock is already held](https://help.ably.io/error/101002)** + Occurs when attempting to acquire a lock that another member currently holds + +• **[101003 - Lock was released](https://help.ably.io/error/101003)** + The lock was explicitly released by the holding member or expired + +• **[101000 - Space not found](https://help.ably.io/error/101000)** + The specified Space does not exist or has not been initialized + +• **[101001 - Invalid Space operation](https://help.ably.io/error/101001)** + An invalid operation was attempted on a Space component ## Need Further Help? @@ -173,43 +244,50 @@ Our team will help you resolve this issue as quickly as possible. - + + + \ No newline at end of file From f6ac8b32d31d04920c1d481c55b23f178493a875 Mon Sep 17 00:00:00 2001 From: Matthew O'Riordan Date: Tue, 26 Aug 2025 08:16:00 +0200 Subject: [PATCH 5/6] Regenerate all error code docs Token intensive! Took a few Claude Code runs --- .../errors/codes/0-generic-client-error.mdx | 86 ++-- .../platform/errors/codes/1-unknown-error.mdx | 55 +-- .../10000-no-error-operational-state.mdx | 145 ++++--- .../codes/100000-asset-tracking-sdk-error.mdx | 207 ++++++---- .../100001-invalid-asset-tracking-message.mdx | 83 ++-- .../codes/100002-token-fetch-failed.mdx | 74 ++-- ...-asset-tracking-authentication-failure.mdx | 145 ++++--- .../codes/100004-subscriber-never-online.mdx | 65 ++-- .../codes/100005-subscriber-not-online.mdx | 83 ++-- .../codes/101000-space-name-missing.mdx | 53 +-- .../errors/codes/101001-not-entered-space.mdx | 72 ++-- .../101002-lock-request-already-exists.mdx | 186 +++++---- .../errors/codes/101003-lock-is-locked.mdx | 75 ++-- .../errors/codes/101004-lock-invalidated.mdx | 72 ++-- .../errors/codes/10200-unrecognized-error.mdx | 52 ++- .../codes/102100-room-discontinuity.mdx | 334 +++++++++++----- .../codes/102101-room-in-failed-state.mdx | 126 ++++-- .../errors/codes/102102-room-is-releasing.mdx | 139 ++++--- .../errors/codes/102103-room-is-released.mdx | 367 +++++++++++++----- ...om-released-before-operation-completed.mdx | 114 ++++-- .../codes/102107-room-invalid-state.mdx | 221 ++++++++--- .../codes/20000-informational-status.mdx | 58 +-- .../errors/codes/40000-bad-request.mdx | 167 +++++--- .../codes/40001-invalid-request-body.mdx | 193 +++++---- .../codes/40003-invalid-parameter-value.mdx | 123 +++--- .../errors/codes/40004-invalid-header.mdx | 107 +++-- .../errors/codes/40005-invalid-credential.mdx | 144 ++++--- .../codes/40006-invalid-connection-id.mdx | 85 ++-- .../codes/40008-invalid-content-length.mdx | 177 +++++---- .../codes/40009-message-size-exceeded.mdx | 305 +++++++++++---- .../codes/40010-invalid-channel-name.mdx | 168 +++++--- .../errors/codes/40011-stale-ring-state.mdx | 203 +++++++--- .../errors/codes/40012-invalid-client-id.mdx | 205 ++++++---- ...40013-invalid-message-data-or-encoding.mdx | 134 +++++-- .../errors/codes/40014-resource-disposed.mdx | 132 ++++--- .../errors/codes/40015-invalid-device-id.mdx | 127 ++++-- .../40017-unsupported-protocol-version.mdx | 135 ++++--- .../codes/40018-delta-decode-failure.mdx | 134 +++++-- .../errors/codes/40019-missing-plugin.mdx | 115 +++--- .../codes/40020-batch-partial-failure.mdx | 153 +++++--- ...invalid-resource-or-deprecated-feature.mdx | 65 ++-- .../codes/40023-protocol-version-required.mdx | 89 +++-- .../codes/40024-channel-mode-required.mdx | 201 +++++++--- .../codes/40030-invalid-publish-request.mdx | 68 ++-- .../errors/codes/40031-invalid-message-id.mdx | 78 ++-- .../codes/40032-invalid-extras-field.mdx | 82 ++-- .../codes/40099-internal-testing-error.mdx | 107 +++-- .../codes/40100-unauthorized-access.mdx | 155 +++++--- .../codes/40101-invalid-credentials.mdx | 133 ++++--- .../codes/40102-incompatible-credentials.mdx | 162 +++++--- .../codes/40103-basic-auth-requires-tls.mdx | 161 +++++--- .../codes/40104-timestamp-not-current.mdx | 161 ++++++-- ...106-missing-authentication-credentials.mdx | 132 +++++-- .../errors/codes/40113-account-blocked.mdx | 51 +-- .../40115-account-request-limit-exceeded.mdx | 38 +- .../40121-token-revocation-not-enabled.mdx | 157 ++++---- .../errors/codes/40130-key-removed.mdx | 82 ++-- .../errors/codes/40131-key-revoked.mdx | 89 +++-- .../errors/codes/40132-api-key-expired.mdx | 91 +++-- ...3-token-revocation-authorization-error.mdx | 91 +++-- .../codes/40140-token-error-unspecified.mdx | 132 ++++--- .../errors/codes/40142-token-expired.mdx | 106 +++-- .../codes/40144-invalid-jwt-token-format.mdx | 98 +++-- .../codes/40146-unsupported-token-claims.mdx | 71 ++-- .../40149-token-error-range-boundary.mdx | 129 +++--- .../codes/40160-insufficient-capabilities.mdx | 121 ++++-- ...-namespace-requires-identified-clients.mdx | 179 +++++---- ...2-token-revocation-requires-basic-auth.mdx | 67 ++-- ...key-missing-revocable-tokens-attribute.mdx | 102 +++-- .../codes/40170-auth-callback-error.mdx | 189 ++++++--- .../40171-token-renewal-not-configured.mdx | 150 ++++--- .../platform/errors/codes/40300-forbidden.mdx | 128 ++++-- ...40331-placement-constraint-environment.mdx | 66 ++-- .../40332-placement-constraint-violation.mdx | 149 ++++--- .../errors/codes/40400-resource-not-found.mdx | 162 ++++---- .../errors/codes/40500-method-not-allowed.mdx | 83 ++-- .../errors/codes/40800-request-timeout.mdx | 163 +++++--- ...1-message-rejected-before-publish-rule.mdx | 68 ++-- .../42213-message-rejected-by-moderation.mdx | 94 +++-- .../42922-rate-limit-too-many-requests.mdx | 91 +++-- .../errors/codes/49900-call-cancelled.mdx | 98 +++-- .../codes/50001-internal-channel-error.mdx | 77 ++-- .../codes/50002-internal-connection-error.mdx | 125 ++++-- .../errors/codes/50003-timeout-error.mdx | 244 +++++++----- ...004-service-unavailable-capacity-limit.mdx | 103 +++-- .../errors/codes/50005-service-lockdown.mdx | 135 ++++--- .../codes/50010-internal-server-error.mdx | 96 +++-- .../errors/codes/50210-bad-gateway.mdx | 174 ++++++--- .../codes/50300-service-unavailable.mdx | 73 ++-- .../codes/50310-edge-service-unavailable.mdx | 210 ++++++---- .../errors/codes/50400-gateway-timeout.mdx | 159 +++++--- .../50410-edge-proxy-gateway-timeout.mdx | 88 +++-- ...1002-push-activation-clientid-mismatch.mdx | 172 +++++--- .../errors/codes/65536-not-an-error-code.mdx | 84 ++-- ...3-integration-max-concurrency-exceeded.mdx | 104 +++-- ...04-integration-invalid-message-content.mdx | 124 ++++-- .../errors/codes/70005-amqp-queue-timeout.mdx | 133 ++++--- .../errors/codes/70006-amqp-backpressure.mdx | 72 ++-- .../errors/codes/80000-connection-failed.mdx | 89 +++-- .../codes/80002-connection-suspended.mdx | 163 +++++--- ...003-connection-temporarily-unavailable.mdx | 164 ++++++-- .../80008-connection-recovery-expired.mdx | 222 +++++++---- ...80009-connection-transport-unavailable.mdx | 97 +++-- .../codes/80010-invalid-transport-handle.mdx | 71 ++-- .../errors/codes/80013-protocol-error.mdx | 235 +++++++---- .../errors/codes/80014-connection-timeout.mdx | 233 +++++++---- ...016-operation-on-superseded-connection.mdx | 75 ++-- .../errors/codes/80017-connection-closed.mdx | 98 +++-- .../codes/80018-invalid-connection-id.mdx | 229 +++++++---- .../80019-auth-provider-request-failed.mdx | 165 +++++--- ...to-resume-connection-from-another-site.mdx | 283 +++++++++----- .../codes/90000-channel-operation-failed.mdx | 135 +++++-- ...channel-operation-failed-invalid-state.mdx | 149 +++++-- ...le-to-recover-channel-messages-expired.mdx | 160 ++++++-- .../codes/90004-message-limit-exceeded.mdx | 149 +++++-- ...90005-channel-recovery-epoch-not-found.mdx | 132 ++++--- .../codes/90007-channel-operation-timeout.mdx | 117 ++++-- .../codes/90010-channel-limit-exceeded.mdx | 156 +++++--- .../codes/90099-generic-discontinuity.mdx | 55 ++- .../91000-presence-requires-client-id.mdx | 91 +++-- .../91001-presence-channel-invalid-state.mdx | 143 +++++-- .../91004-presence-auto-reenter-failed.mdx | 89 +++-- .../91005-presence-state-out-of-sync.mdx | 140 ++++--- .../91100-member-implicitly-left-presence.mdx | 256 ++++++++---- .../92000-liveobjects-validation-error.mdx | 234 +++++++---- .../errors/codes/92001-conflicting-usage.mdx | 137 +++++-- .../codes/92002-cipher-algorithm-mismatch.mdx | 104 +++-- .../codes/92003-cipher-decryption-failed.mdx | 132 ++++--- ...04-dual-purpose-cipher-or-object-error.mdx | 198 +++++----- .../codes/92005-duplicate-context-error.mdx | 72 ++-- .../codes/92100-encoding-value-too-long.mdx | 77 ++-- ...3001-annotations-channel-state-invalid.mdx | 91 +++-- ...3002-mutable-messages-feature-required.mdx | 131 ++++--- 133 files changed, 11530 insertions(+), 5973 deletions(-) diff --git a/src/pages/docs/platform/errors/codes/0-generic-client-error.mdx b/src/pages/docs/platform/errors/codes/0-generic-client-error.mdx index c74a50ac21..b9f85c81f0 100644 --- a/src/pages/docs/platform/errors/codes/0-generic-client-error.mdx +++ b/src/pages/docs/platform/errors/codes/0-generic-client-error.mdx @@ -1,13 +1,13 @@ - + - + # Error 0: Generic client error @@ -38,8 +38,14 @@ You may see various messages with this error code, including: - "must be NSString NSData NSArray or NSDictionary" - Invalid data type - "Token details are empty" - Authentication token missing - "Unknown error" - Generic fallback when specific error unavailable +- "channel has detached" - Channel detachment occurred +- "Can't ping a [state] connection" - Invalid connection state for ping +- "encrypt failed" - Encryption operation failure +- "base64 failed" - Base64 encoding failure +- "cannot use device before device activation has finished" - Device not activated +- "cannot subscribe/unsubscribe with null client ID" - Client ID required for operation - + ## Common Causes @@ -47,56 +53,56 @@ You may see various messages with this error code, including: - Push notification recipient or data not provided - Device token missing during activation - Client ID null for operations requiring authentication - + 2. **Network connectivity issues** (23% of cases) - No internet connection detected - Connection timeout during initialization - Connection closed unexpectedly - + 3. **Invalid data types or encoding** (18% of cases) - Data type not supported for encoding - Encryption or Base64 encoding failure - Unsupported data format provided - + 4. **Generic SDK errors** (14% of cases) - Exception conversion to error format - Unknown error conditions - Fallback when no specific code available - + ## Resolution Steps 1. **Read the error message carefully** - Error code 0 is generic, so the message contains the specific issue - Look for details about missing parameters or validation failures - + 2. **For missing parameter errors** - Review the SDK documentation for required parameters - Ensure all mandatory fields are provided - Check parameter types match expectations - + 3. **For network connectivity issues** - Verify internet connection is available - Check firewall or proxy settings - Ensure the Ably service endpoints are accessible - + 4. **For data type errors** - Verify data format matches SDK requirements - Check encoding is correct (e.g., UTF-8 for strings) - Ensure data size is within limits - + 5. **Enable detailed logging** - Turn on debug logging in your SDK - Capture the full error context - Look for additional error details that may help diagnose the issue - + ## Automatic Handling @@ -108,7 +114,7 @@ This is a client-side validation or SDK error that will not be automatically ret - Implement proper error handling for all SDK operations - Keep your SDK updated to the latest version for improved error handling - Use typed interfaces where available to catch errors at compile time - + ## SDK-Specific Behavior @@ -118,19 +124,19 @@ Most extensive use of error code 0 for: - Device activation checks - Data encoding validation - Connection state errors - + ### Rust (ably-rust) Uses `ErrorCode::NotSet` variant: - Default when no specific error code provided - Fallback for unmappable HTTP status codes - + ### Swift Asset Tracking Connection lifecycle errors: - Connection timeout during startup - Connection closed during initialization - + ## Important Notes @@ -140,7 +146,7 @@ Error code 0 is **not an official Ably protocol error code**. It's used internal - SDK-level errors that don't correspond to server errors This should not be confused with error code 10000, which means "no error" or successful operation. - + ## Related Resources @@ -149,6 +155,17 @@ This should not be confused with error code 10000, which means "no error" or suc - [Push Notifications Documentation](https://ably.com/docs/push) - [Connection State Management](https://ably.com/docs/realtime/connection) +## Related Errors + +• **[10000 - No Error](https://help.ably.io/error/10000)** + Success status - semantically opposite to error code 0's usage as a generic error + +• **[40000 - Bad Request](https://help.ably.io/error/40000)** + Server-side validation errors that may occur after client-side validation passes + +• **[80000 - Connection Failed](https://help.ably.io/error/80000)** + Specific connection failures with proper error codes, unlike generic code 0 network issues + ## Need Further Help? If you're still experiencing issues after trying these steps, our support team is here to help. @@ -168,29 +185,29 @@ Our team will help you resolve this issue as quickly as possible. - + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/1-unknown-error.mdx b/src/pages/docs/platform/errors/codes/1-unknown-error.mdx index c2816c7172..87d262d1d0 100644 --- a/src/pages/docs/platform/errors/codes/1-unknown-error.mdx +++ b/src/pages/docs/platform/errors/codes/1-unknown-error.mdx @@ -1,13 +1,13 @@ - + - + # Error 1: Unknown error @@ -40,17 +40,17 @@ The actual error details from the server are preserved in the message field. 1. **SDK version mismatch** (most common) - Using an older SDK version while the API has introduced new error codes - The server returned an error code that your SDK version doesn't recognize - + 2. **Beta or experimental features** - Accessing features that return error codes not yet in general release - Platform-specific error codes for your account - + 3. **Corrupted response data** - Malformed error responses with invalid error code values - Network issues causing response corruption - + ## Resolution Steps @@ -58,7 +58,7 @@ The actual error details from the server are preserved in the message field. - Check your current version in `Cargo.toml` - Update to the latest version: `cargo update -p ably` - The latest SDK version will recognize more error codes - + 2. **Examine the full error details** - The original error message from the server is preserved @@ -76,17 +76,17 @@ The actual error details from the server are preserved in the message field. } } ``` - + 3. **Enable verbose logging** - Capture the raw JSON response to see the original error code - This helps identify what specific error the server returned - + 4. **Check Ably documentation** - Review the latest error codes at https://ably.com/docs/errors - Look for any recent API changes or new features - + ## Automatic Handling @@ -94,7 +94,7 @@ This error code is specific to the Rust SDK's deserialization process. When the - It automatically maps it to error code 1 (UnknownError) - The original error message and details are preserved - The SDK continues to function without parsing failures - + ## Prevention @@ -128,11 +128,11 @@ Our team will help you resolve this issue as quickly as possible. - @@ -153,14 +153,14 @@ Our team will help you resolve this issue as quickly as possible. @@ -172,11 +172,14 @@ Our team will help you resolve this issue as quickly as possible. - Severity: Low (rare occurrence, SDK-specific) --> + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/10000-no-error-operational-state.mdx b/src/pages/docs/platform/errors/codes/10000-no-error-operational-state.mdx index 270d824bdb..1cbb33a85d 100644 --- a/src/pages/docs/platform/errors/codes/10000-no-error-operational-state.mdx +++ b/src/pages/docs/platform/errors/codes/10000-no-error-operational-state.mdx @@ -1,13 +1,13 @@ - + - + # Error 10000: No error (operational state) @@ -25,43 +25,45 @@ You received a status code that indicates a successful operation or an intention ## Quick Fix - If you see "Can't attach when not in an active state": Wait for the connection to become active before attaching channels -- If your app just returned from background: Re-establish the connection first +- If your app just returned from background (especially Flutter/Android): Re-establish the connection first - For message filtering scenarios: This is intentional behavior, no action needed +- For "Connection closed by client": Normal termination, reconnect if needed ## Error Messages You may see one of these messages: -- "Connection closed by client" -- "Can't attach when not in an active state" -- "Discarding message; not local origin" -- "Message discarded by perMessageTransform" +- "Connection closed by client" (.NET SDK) +- "Can't attach when not in an active state" (Java SDK) +- "Discarding message; not local origin" (Server-side filtering) +- "Message discarded by perMessageTransform" (Integration rules) ## Common Causes 1. **Channel operations on inactive connections** (40% of cases) - + - Attempting to attach channels when connection isn't active - - App returning from background state on mobile devices + - App returning from background state on mobile devices (especially Android/Flutter) - Connection not yet established or already closed + - Common after app restart without proper connection handling 2. **Client-initiated connection closure** (30% of cases) - + - Normal connection termination by your application - Explicit disconnect() calls - - App shutdown or cleanup + - App shutdown or cleanup routines 3. **Message filtering by server rules** (30% of cases) - + - Messages from non-local origins when local-only rules apply - Messages discarded by transformation functions - - Intentional server-side filtering + - Intentional server-side filtering via integration rules ## Resolution Steps ### For "Can't attach when not in an active state" 1. **Check connection state before operations** - + ```javascript // Wait for connection to be ready ably.connection.on('connected', () => { @@ -71,31 +73,39 @@ You may see one of these messages: }); ``` -2. **Handle mobile app lifecycle events** - +2. **Handle mobile app lifecycle events (Android/Flutter)** + ```javascript // Re-establish connection when app returns from background document.addEventListener('resume', () => { + // For Flutter/Android apps, always reconnect after resuming ably.connection.connect(); }); + + // For Flutter specifically + WidgetsBinding.instance.addObserver(LifecycleEventHandler( + resumeCallBack: () async { + await ably.connection.connect(); + } + )); ``` 3. **Monitor connection state changes** - + ```javascript ably.connection.on('disconnected', () => { console.log('Connection lost, will auto-reconnect'); }); ably.connection.on('connected', () => { - console.log('Connection restored'); + console.log('Connection restored, safe to attach channels'); }); ``` ### For "Connection closed by client" This indicates normal operation - your application explicitly closed the connection. No recovery needed unless you want to reconnect: - + ```javascript // To reconnect after closing @@ -105,38 +115,65 @@ ably.connection.connect(); ### For Message Filtering Messages with "not local origin" or "discarded by perMessageTransform" are intentionally filtered based on your integration rules. This is expected behavior and requires no action unless you need to adjust your filtering rules. - + + +To review or modify filtering rules: +1. Access your Ably dashboard +2. Navigate to the Integrations tab +3. Review your webhook and message rules +4. Adjust channel filters or transformation functions as needed ## Automatic Handling Ably SDKs handle connection state transitions automatically: - -- Automatic reconnection when connections drop + +- Automatic reconnection when connections drop (every 15 seconds for up to 2 minutes) - State recovery within 2 minutes of disconnection - Channel reattachment after reconnection +- Transition to suspended state after 2 minutes (reconnection attempts every 30 seconds) For error 10000 specifically, the SDK doesn't retry automatically since it represents successful operations or intentional states. ## Prevention -### For Mobile Applications - +### For Mobile Applications (Especially Flutter/Android) + - Implement proper app lifecycle handling - Re-establish connections after backgrounding - Don't attempt operations immediately after foreground transition +- For Flutter: Handle app restarts differently from fresh runs +- Consider implementing a connection manager for state transitions ### For Channel Operations - + - Always check connection state before channel operations - Use connection state listeners to coordinate operations - Handle connection state transitions gracefully +- Implement retry logic with appropriate delays for mobile apps + +### For Integration Rules +- Review filtering patterns in your integration configuration +- Test transformation functions thoroughly +- Monitor filtered message patterns for unexpected discards ## Related Resources -- [Connection state management](https://ably.com/docs/realtime/connection) -- [Channel lifecycle](https://ably.com/docs/realtime/channels#attach) -- [Mobile app best practices](https://ably.com/docs/best-practice#mobile) -- [Message filtering and transformations](https://ably.com/docs/general/integrations) +- [Connection states and recovery](https://ably.com/docs/connect/states) +- [Channel concepts and attachment](https://ably.com/docs/channels) +- [Channel states documentation](https://ably.com/docs/channels/states) +- [Webhook integrations and filtering](https://ably.com/docs/integrations/webhooks) +- [API Reference - Connection](https://ably.com/docs/api/realtime-sdk/connection) + +## Related Errors + +• **[80000 - Connection Failed](https://help.ably.io/error/80000)** + Occurs when the connection cannot be established, unlike 10000 which indicates intentional closure or state restrictions + +• **[80002 - Connection Suspended](https://help.ably.io/error/80002)** + Related state after prolonged disconnection (2+ minutes), prevents operations similar to 10000's attach restrictions + +• **[80003 - Connection Disconnected](https://help.ably.io/error/80003)** + Temporary disconnection state, may lead to 10000 errors if operations attempted during recovery ## Need Further Help? @@ -147,9 +184,10 @@ If you're still experiencing issues after trying these steps, our support team i When contacting support, please provide: - Your account ID and app ID - The full error message including error code 10000 -- Steps to reproduce the issue +- Steps to reproduce the issue (especially for mobile apps, include lifecycle events) - Any relevant code snippets (without sensitive credentials) -- The SDK and version you're using +- The SDK and version you're using (particularly important for Flutter issues) +- Whether the issue occurs after app restart or fresh launch Our team will help you resolve this issue as quickly as possible. @@ -158,33 +196,38 @@ Our team will help you resolve this issue as quickly as possible. + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/100000-asset-tracking-sdk-error.mdx b/src/pages/docs/platform/errors/codes/100000-asset-tracking-sdk-error.mdx index 7b4a44d57b..4890462329 100644 --- a/src/pages/docs/platform/errors/codes/100000-asset-tracking-sdk-error.mdx +++ b/src/pages/docs/platform/errors/codes/100000-asset-tracking-sdk-error.mdx @@ -1,20 +1,20 @@ - + - + # Error 100000: Asset Tracking SDK error ## What Happened -The Asset Tracking SDK encountered an internal error while processing your request. +The Asset Tracking SDK encountered an internal error while processing your request. This is a catch-all error code for various SDK-specific issues that require application-level handling. ## Quick Reference @@ -25,8 +25,9 @@ The Asset Tracking SDK encountered an internal error while processing your reque ## Quick Fix - Check the error message for specific details about what went wrong -- Verify your Asset Tracking SDK configuration is complete -- Ensure the publisher or subscriber is in an active state before operations +- Verify your Asset Tracking SDK configuration is complete with all required parameters +- Ensure the publisher or subscriber is in an active state before performing operations +- Validate location data before sending (coordinates must be within valid ranges) ## Error Messages @@ -42,101 +43,150 @@ You'll see various messages depending on the specific issue: - "Cannot perform this action when publisher is stopped." - "Cannot perform this action when subscriber is stopped." - "Publisher is either stopped or stopping." +- "Cannot perform EnhancedLocationChangedEvent. Publisher is either stopped or stopping." +- "Cannot perform RawLocationChanged. Publisher is either stopped or stopping." +- "Cannot perform RefreshResolutionPolicyEvent. Publisher is either stopped or stopping." +- "Cannot perform ChangeLocationEngineResolution. Publisher is either stopped or stopping." +- "Cannot perform PresenceMessageEvent. Publisher is either stopped or stopping." ### Location Validation Errors - "Latitude out of range [-90, 90]. Received: ({latitude})" - "Longitude out of range [-180, 180]. Received: ({longitude})" - "Invalid horizontal accuracy got {value}" -- "{parameter} must be finite, got {value}" +- "{parameter} must be finite, got {value}" (for latitude, longitude, altitude, speed, etc.) +- "timestamp must be non-zero and finite, got {timestamp}" +- "Invalid KPI value" +- "Invalid count of coordinates in GeoJSONGeometry. Received: {coordinates}" -### Other Common Errors -- "Error while parsing: {object/json}" +### Connection & Channel Errors +- "Cannot close connection" - "Attempt to send location while not tracked channel" + +### Location Service Errors +- "PassiveLocationManager.stopRecordingHistory did not return a file URL" +- "HistoryReader(fileUrl:) returned nil" +- "PublisherError || ErrorMessage: {localizedDescription}" (CoreLocation errors) + +### Route Provider Errors +- "Missing route in Directions response." - "Provider is already calculating route." +### JSON Serialization Errors +- "Error while parsing: {object/json}" +- "Error while parsing: Not supported input type{type}" + ## Common Causes 1. **Incomplete SDK configuration** (40% of cases) - + - Missing required configuration parameters - - Forgetting to call builder methods - - Invalid connection or authentication setup + - Forgetting to call builder methods during initialization + - Invalid connection configuration or authentication setup + - Missing Mapbox configuration for publisher 2. **Operations on stopped components** (30% of cases) - + - Attempting to publish locations after stopping the publisher - Trying to track assets with a stopped subscriber - - Performing actions during shutdown + - Performing operations during shutdown sequence + - Event processing while component is in stopping state 3. **Invalid location data** (20% of cases) - - - Coordinates outside valid ranges - - Non-finite values (NaN or infinity) - - Invalid timestamp or accuracy values + + - Coordinates outside valid geographic ranges + - Non-finite values (NaN or infinity) in numeric fields + - Invalid or zero timestamps + - Negative accuracy values 4. **JSON serialization issues** (10% of cases) - - - Failed encoding/decoding of data - - Unsupported input types - - Malformed JSON structures + + - Failed encoding/decoding of Codable objects + - Unsupported input types for conversion + - Malformed JSON structures in data exchange ## Resolution Steps 1. **For configuration errors** - - - Review your SDK initialization code + + - Review your SDK initialization code thoroughly - Ensure all required builder methods are called: - - `.connection()` for connection configuration - - `.trackingId()` for subscriber setup - - `.mapboxConfiguration()` for publisher setup - - `.resolutionPolicyFactory()` for location resolution - - Verify your Ably API key is correct + - `.connection()` with valid ConnectionConfiguration + - `.trackingId()` for subscriber setup (required) + - `.mapboxConfiguration()` for publisher setup (required) + - `.resolutionPolicyFactory()` for location resolution settings + - Verify your Ably API key is correct and has proper capabilities + - Check that all configuration objects are properly instantiated 2. **For state management errors** - - - Check the component state before performing operations - - Re-initialize stopped publishers or subscribers: + + - Always check component state before performing operations + - Re-initialize stopped publishers or subscribers as needed: ```swift // Check state before operations if publisher.isStopped { - // Re-initialize or restart the publisher - publisher = createNewPublisher() + // Re-initialize the publisher + publisher = try await createNewPublisher() } ``` - + + - Implement proper lifecycle management + - Avoid operations during shutdown sequences 3. **For location validation errors** - - - Validate location data before sending: - - Latitude must be between -90 and 90 - - Longitude must be between -180 and 180 + + - Validate all location data before processing: + - Latitude must be between -90 and 90 degrees + - Longitude must be between -180 and 180 degrees - All numeric values must be finite (not NaN or infinity) - - Check GPS permissions are granted - - Handle CoreLocation errors appropriately + - Timestamps must be non-zero and valid + - Accuracy values must be positive + - Ensure GPS/location permissions are properly granted + - Handle CoreLocation framework errors appropriately + - Consider implementing location data sanitization 4. **For JSON errors** - + - Validate data structures before serialization - - Use proper error handling around encoding/decoding - - Check for unsupported data types + - Implement proper error handling around encoding/decoding operations + - Check for unsupported data types in your models + - Ensure Codable conformance for all serialized types + +5. **For connection and channel errors** + + - Verify network connectivity before operations + - Ensure tracked channel is properly established + - Handle connection lifecycle events appropriately + - Implement reconnection logic for network interruptions ## Automatic Handling -This is an SDK-internal error that requires application-level handling. The Asset Tracking SDK does not automatically retry these errors as they typically indicate configuration or state issues that must be resolved programmatically. +This is an SDK-internal error that requires application-level handling. The Asset Tracking SDK does not automatically retry these errors as they typically indicate configuration, state, or validation issues that must be resolved programmatically before retry would succeed. ## Prevention -- Initialize SDK components with all required configuration parameters -- Implement proper lifecycle management for publishers and subscribers -- Validate location data before processing -- Use try-catch blocks around Asset Tracking operations -- Maintain awareness of component states (active/stopped) +- **Configuration**: Always initialize SDK components with all required configuration parameters +- **State Management**: Implement proper lifecycle management for publishers and subscribers +- **Validation**: Validate all location data before processing or sending +- **Error Handling**: Use comprehensive try-catch blocks around Asset Tracking operations +- **State Awareness**: Maintain awareness of component states (active/stopped/stopping) +- **Testing**: Test edge cases including network interruptions and GPS signal loss +- **Logging**: Implement detailed error logging to identify patterns ## Related Resources - [Asset Tracking documentation](https://ably.com/docs/asset-tracking) -- [Asset Tracking SDK setup guide](https://ably.com/docs/asset-tracking/setup) -- [Location data best practices](https://ably.com/docs/asset-tracking/location-data) +- [Using the Asset Tracking SDKs](https://ably.com/docs/asset-tracking/using-the-sdks) +- [Asset Tracking example apps](https://ably.com/docs/asset-tracking/example-apps) + +## Related Errors + +Since error 100000 is a catch-all for Asset Tracking SDK errors, you may also encounter these related SDK-specific error codes: + +• **[100001 - Protocol Format Error](https://help.ably.io/error/100001)** + Invalid protocol format in Asset Tracking communication + +• **[100002-100005 - Asset Tracking Specific Errors](https://help.ably.io/error/100002)** + Various specialized Asset Tracking error scenarios ## Need Further Help? @@ -157,43 +207,50 @@ Our team will help you resolve this issue as quickly as possible. - + + + @@ -202,6 +259,6 @@ To improve this error code documentation: 1. First approach: Update editorial-notes.md in ably-os repository with specific guidance for error 100000 2. Regenerate: Run `./bin/ably-os errors document-error-codes 100000 --force` 3. For broader improvements: Review and update ably-os prompt templates -4. Context: See https://github.com/ably/ably-os/blob/main/docs/ERROR_COMMANDS_GUIDE.md +4. Context: See https://github.com/ably/ably-os/blob/5f4ba43/docs/ERROR_COMMANDS_GUIDE.md 5. Source repository: https://github.com/ably/ably-os --> \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/100001-invalid-asset-tracking-message.mdx b/src/pages/docs/platform/errors/codes/100001-invalid-asset-tracking-message.mdx index 2e04a739a2..d656fbfbc6 100644 --- a/src/pages/docs/platform/errors/codes/100001-invalid-asset-tracking-message.mdx +++ b/src/pages/docs/platform/errors/codes/100001-invalid-asset-tracking-message.mdx @@ -1,26 +1,29 @@ - + - + # Error 100001: Invalid Asset Tracking message format ## What Happened -The Asset Tracking SDK received a message that doesn't match the expected format for location updates. + +The Asset Tracking SDK received a message that doesn't match the expected JSON format required for location updates. ## Quick Reference + | Error Code | HTTP Status | Category | Retryable | |------------|-------------|----------|-----------| | 100001 | 400 | Protocol Error (Asset Tracking) | No - requires fixing message format | ## Quick Fix + - Ensure all Asset Tracking messages are JSON strings - Use SDK-provided methods for publishing location updates - Verify publisher and subscriber SDK versions are compatible @@ -37,17 +40,20 @@ You may see one of these messages: 1. **Non-string message data** (most common) - Publishing raw objects instead of JSON strings - Using direct channel publishing instead of SDK methods - + - Sending binary data or numeric values + 2. **Malformed JSON** - Invalid JSON syntax in message strings - Missing required fields in location update messages - + - Incorrect escaping or encoding + 3. **Protocol version mismatch** - Publisher and subscriber using incompatible SDK versions - Custom implementations not following Asset Tracking protocol - + - Mixing different Asset Tracking SDK generations + ## Resolution Steps @@ -55,25 +61,25 @@ You may see one of these messages: - Asset Tracking messages must be JSON strings - Use SDK publishing methods, not direct Ably channel publishing - Messages must conform to `RawLocationUpdateMessage` or `EnhancedLocationUpdateMessage` schemas - + 2. **Use SDK-provided methods** - For publishers: Use Asset Tracking Publisher SDK methods - For subscribers: Use Asset Tracking Subscriber SDK methods - - Avoid manual message construction - + - Avoid manual message construction or direct channel operations + 3. **Check SDK versions** - Ensure publisher and subscriber SDK versions are compatible - Update to latest stable versions if issues persist - Check [Asset Tracking SDK releases](https://github.com/ably/ably-asset-tracking-swift/releases) for compatibility notes - + 4. **Validate JSON structure** - Test JSON parsing before publishing - Include all required fields for location updates - Use typed message construction rather than string concatenation - + ## Automatic Handling @@ -82,7 +88,7 @@ When error 100001 occurs: - The trackable connection is automatically disconnected - No automatic retry occurs - manual intervention required - You must fix the message format and reconnect - + ## Prevention @@ -90,13 +96,25 @@ When error 100001 occurs: - **Version management**: Maintain consistent SDK versions across publisher and subscriber - **Schema validation**: Implement message validation in development environments - **Testing**: Include protocol error scenarios in integration tests - + ## Related Resources -- [Asset Tracking documentation](https://ably.com/docs/asset-tracking) + - [Asset Tracking Swift SDK](https://github.com/ably/ably-asset-tracking-swift) +- [Asset Tracking Android SDK](https://github.com/ably/ably-asset-tracking-android) - [Asset Tracking protocol specification](https://github.com/ably/ably-asset-tracking-common/tree/main/specification) -- Related errors: Other Asset Tracking errors in the 100xxx range +- [Ably documentation](https://ably.com/docs) + +## Related Errors + +• **[80002 - Connection Suspended](https://help.ably.io/error/80002)** + Connection enters suspended state after extended disconnection, affecting Asset Tracking connections + +• **[80000 - Connection Failed](https://help.ably.io/error/80000)** + General connection failure that may impact Asset Tracking message delivery + +• **[92001 - Encryption Error](https://help.ably.io/error/92001)** + Message encryption/decryption issues that could affect encrypted Asset Tracking messages ## Need Further Help? @@ -118,10 +136,10 @@ Our team will help you resolve this issue as quickly as possible. @@ -134,17 +152,20 @@ Our team will help you resolve this issue as quickly as possible. + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/100002-token-fetch-failed.mdx b/src/pages/docs/platform/errors/codes/100002-token-fetch-failed.mdx index b30ec6cd38..90a50a6fb6 100644 --- a/src/pages/docs/platform/errors/codes/100002-token-fetch-failed.mdx +++ b/src/pages/docs/platform/errors/codes/100002-token-fetch-failed.mdx @@ -1,13 +1,13 @@ - + - + # Error 100002: Token fetch failed @@ -61,34 +61,34 @@ You may see: - The Asset Tracking SDK will automatically retry with exponential backoff - Most token fetch failures resolve within a few retry attempts - No immediate action required for transient failures - + 2. **Verify token server availability** - Check your token server is running and accessible - Review server logs for any error messages - Confirm the token endpoint URL is correct - Test the endpoint manually with a curl request - + 3. **Check network connectivity** - Verify device has internet connectivity - Ensure firewall rules allow access to token server - Check DNS resolution for token server hostname - Confirm SSL/TLS certificates are valid - + 4. **Review token callback implementation** - Ensure proper timeout configuration (recommended: 30 seconds) - Verify error handling in your token callback - Check for any exceptions in callback code - Follow SDK documentation examples for implementation - + 5. **Monitor for persistent failures** - If error continues after multiple retries (>2 minutes), investigate server health - Check server capacity and consider scaling if under high load - Review authentication service dependencies - + ## Automatic Handling @@ -99,7 +99,7 @@ The Asset Tracking SDK automatically: - Falls back to error 100003 only for non-retriable failures You don't need to implement custom retry logic. - + ## Prevention @@ -107,14 +107,18 @@ You don't need to implement custom retry logic. - **Monitoring and Alerting**: Implement health checks and alerts for token endpoint availability - **Connection Configuration**: Use connection pooling and appropriate timeout settings - **Error Handling**: Implement comprehensive error callbacks in your token authentication flow - + ## Related Resources - [Asset Tracking Android SDK Documentation](https://github.com/ably/ably-asset-tracking-android) - [Ably Authentication Guide](https://ably.com/docs/auth) - [Token Authentication Best Practices](https://ably.com/docs/auth/token) -- Related error: [100003 - Non-retriable token failure](./100003-token-auth-failed.md) + +## Related Errors + +• **[100003 - Non-retriable token failure](https://help.ably.io/error/100003)** + Occurs when token authentication fails permanently and cannot be retried, unlike 100002 which is retriable ## Need Further Help? @@ -135,39 +139,41 @@ Our team will help you resolve this issue as quickly as possible. + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/100003-asset-tracking-authentication-failure.mdx b/src/pages/docs/platform/errors/codes/100003-asset-tracking-authentication-failure.mdx index 787360b14a..c12e7bf984 100644 --- a/src/pages/docs/platform/errors/codes/100003-asset-tracking-authentication-failure.mdx +++ b/src/pages/docs/platform/errors/codes/100003-asset-tracking-authentication-failure.mdx @@ -1,13 +1,13 @@ - + - + # Error 100003: Asset Tracking authentication failure @@ -37,74 +37,106 @@ This error occurs specifically in the Ably Asset Tracking Android SDK when authe ## Common Causes - + 1. **Invalid API key configuration** (Most common) - Using an expired or revoked API key - - Copy-paste errors in the API key string - - Using test credentials in production + - Copy-paste errors in the API key string (missing characters, extra spaces) + - Using test credentials in production environment + - API key from wrong Ably application 2. **Insufficient token permissions** - Token lacks Asset Tracking channel capabilities - - Missing publish or presence permissions - - Token server not configured with correct permissions + - Missing publish or presence permissions for tracking channels + - Token server not configured with correct channel patterns + - Capability restrictions preventing location updates 3. **Token server credential issues** - - Token server using invalid Ably credentials - - Wrong application ID in token generation - - Environment variables not properly configured + - Token server using invalid or expired Ably credentials + - Wrong application ID in token generation process + - Environment variables not properly configured on server + - Token server health check failures 4. **Environment mismatch** - Using sandbox credentials for production resources - Using production credentials for sandbox resources + - Deployment scripts using wrong credential sets + - Manual configuration errors during setup ## Resolution Steps - + 1. **Verify your API key** - Log into your [Ably dashboard](https://ably.com/dashboard) - Navigate to your app → "API Keys" tab - - Copy the complete API key (including the app ID prefix) + - Copy the complete API key (including the app ID prefix like `xVLyHw.rPSJgQ:...`) - Replace the invalid key in your Asset Tracking configuration + - Ensure no trailing spaces or line breaks in the key + 2. **Check token server configuration** - - Verify the API key used by your token server is valid - - Ensure the token includes Asset Tracking channel permissions + - Verify the API key used by your token server is valid and not expired + - Ensure the token includes Asset Tracking channel permissions (`tracking:*` or specific patterns) - Test token generation independently before SDK initialization - + - Verify the token includes necessary capabilities: `publish`, `subscribe`, `presence` + 3. **Validate environment configuration** - Confirm you're using the correct Ably application (production vs sandbox) - Verify environment-specific configuration is properly deployed - Check that credential environment variables are correctly set + - Review deployment logs for credential configuration warnings + 4. **Test authentication separately** - Use the Ably dashboard's API Streamer to test your credentials - Verify basic channel publish/subscribe works with your credentials + - Test with a simple Ably SDK connection before Asset Tracking initialization - Once confirmed, retry Asset Tracking SDK initialization + + +5. **Review SDK initialization code** + - Check that credentials are properly passed to the SDK + - Verify no hardcoded test credentials remain in production code + - Ensure proper error handling is implemented for authentication failures + ## Automatic Handling -The Asset Tracking SDK does not automatically retry this error. Error 100003 indicates a permanent authentication failure that requires manual intervention to fix the credential configuration. - +The Asset Tracking SDK does not automatically retry this error. Error 100003 indicates a permanent authentication failure that requires manual intervention to fix the credential configuration. The SDK uses a fail-fast authentication strategy to prevent resource waste on unrecoverable credential issues. + ## Prevention - + + +- **Credential validation**: Test credentials during development and in CI/CD pipelines before deployment +- **Environment management**: Use separate credentials for each environment with clear naming conventions +- **Secure storage**: Store credentials in secure systems like AWS Secrets Manager or Azure Key Vault +- **Regular rotation**: Implement credential rotation procedures with proper notification systems +- **Health monitoring**: Add authentication health checks to your token server endpoints +- **Configuration testing**: Include authentication testing in automated test suites +- **Documentation**: Maintain clear documentation of required configuration parameters + +## Related Errors + +• **[100002 - Retriable Token Fetch Failure](https://help.ably.io/error/100002)** + Temporary authentication issue that the SDK will automatically retry -- **Credential validation**: Test credentials during development and in CI/CD pipelines -- **Environment management**: Use separate credentials for each environment -- **Secure storage**: Store credentials in secure systems like AWS Secrets Manager -- **Regular rotation**: Implement credential rotation procedures -- **Health monitoring**: Add authentication health checks to your token server +• **[100004 - Subscriber Never Connected](https://help.ably.io/error/100004)** + Connection state error that may follow authentication failures + +• **[40160 - Token Capability Issues](https://help.ably.io/error/40160)** + Core Ably error for insufficient token permissions ## Related Resources -- [Asset Tracking Android SDK documentation](https://github.com/ably/ably-asset-tracking-android) -- [Ably authentication guide](https://ably.com/docs/auth) -- [Token authentication documentation](https://ably.com/docs/auth/token) -- [Capability and permissions](https://ably.com/docs/auth/capabilities) +- [Asset Tracking Android SDK](https://github.com/ably/ably-asset-tracking-android) +- [Authentication overview](https://ably.com/docs/auth) +- [Token authentication](https://ably.com/tutorials/token-authentication) +- [Capabilities and permissions](https://ably.com/docs/auth/capabilities) +- [Asset Tracking documentation](https://ably.com/docs/asset-tracking/using-the-sdks) ## Need Further Help? @@ -126,36 +158,51 @@ Our team will help you resolve this issue as quickly as possible. + + + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/100004-subscriber-never-online.mdx b/src/pages/docs/platform/errors/codes/100004-subscriber-never-online.mdx index 37d61c41fa..a81b5b5663 100644 --- a/src/pages/docs/platform/errors/codes/100004-subscriber-never-online.mdx +++ b/src/pages/docs/platform/errors/codes/100004-subscriber-never-online.mdx @@ -1,11 +1,11 @@ - + @@ -51,7 +51,7 @@ This appears as part of the `PublisherPresenceStateChange` when the Asset Tracki 1. **No action required** - This is an informational state, not an error requiring fixes - The SDK automatically transitions away from this state - + 2. **Monitor state transitions** - If using the Asset Tracking SDK, you can observe state changes: @@ -68,13 +68,13 @@ This appears as part of the `PublisherPresenceStateChange` when the Asset Tracki } } ``` - + 3. **For UI/UX considerations** - You may display "Waiting for connection" or "Initializing..." messages - No error messages should be shown to end users - This state will automatically resolve once connection is established - + ## Automatic Handling @@ -94,11 +94,26 @@ This informational state has no performance impact: - No network requests are blocked - Simply indicates the initial state before connection +## Related Errors + +• **[100005 - Subscriber not online](https://help.ably.io/error/100005)** + Occurs when the subscriber was previously online but has lost connection + +• **[100000 - Internal SDK error](https://help.ably.io/error/100000)** + Generic internal error fallback for unexpected Asset Tracking SDK issues + +• **[100002 - Token fetch failure](https://help.ably.io/error/100002)** + Authentication token retrieval failed but can be retried + +• **[100003 - Token authentication failure](https://help.ably.io/error/100003)** + Fatal authentication failure that cannot be automatically resolved + ## Related Resources - [Asset Tracking documentation](https://ably.com/docs/asset-tracking) - [Asset Tracking SDK for Android](https://github.com/ably/ably-asset-tracking-android) -- Related state: Error 100005 (Subscriber not online - connection lost) +- [Asset Tracking Common specification](https://github.com/ably/ably-asset-tracking-common/blob/main/specification/README.md) +- [Ably Support](https://ably.com/support) ## Need Further Help? @@ -119,32 +134,33 @@ Our team will help you resolve this issue as quickly as possible. - + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/100005-subscriber-not-online.mdx b/src/pages/docs/platform/errors/codes/100005-subscriber-not-online.mdx index 0592403034..233685f015 100644 --- a/src/pages/docs/platform/errors/codes/100005-subscriber-not-online.mdx +++ b/src/pages/docs/platform/errors/codes/100005-subscriber-not-online.mdx @@ -1,85 +1,85 @@ - + - + # Error 100005: Subscriber not online -## What happened +## What Happened The Asset Tracking subscriber lost its connection to Ably after successfully establishing an initial connection, causing the publisher presence state to become unknown. -## Quick reference +## Quick Reference | Error Code | HTTP Status | Category | Retryable | |------------|-------------|----------|-----------| | 100005 | N/A | Connection/Presence (Asset Tracking) | Yes - automatic reconnection | -## Quick fix +## Quick Fix - The Asset Tracking SDK automatically handles reconnection when network connectivity is restored - Publisher tracking data from before disconnection is preserved with timestamps - No manual intervention required - the SDK will recover once connectivity returns -## Error messages +## Error Messages You'll see this message in the Asset Tracking Android SDK: - "Subscriber is not online" -## Common causes +## Common Causes 1. **Network connectivity loss** (Most common) - Device loses internet connection - Network switch between WiFi and cellular - Poor network conditions causing disconnection - + 2. **App lifecycle transitions** - App goes to background and loses connection - Device enters power-saving mode - System terminates background services - + 3. **Authentication issues** - Token expires causing disconnection - Authentication credentials become invalid - + -## Resolution steps +## Resolution Steps 1. **Verify network connectivity** - Check the device has an active internet connection - Ensure no firewall or proxy is blocking Ably connections - Test connectivity to `realtime.ably.io` - + 2. **Monitor connection state** - The SDK automatically attempts reconnection with appropriate backoff - Listen for connection state changes to track recovery progress - Publisher presence will automatically update when connection is restored - + 3. **Handle the unknown state gracefully** - Display appropriate UI indicating temporary uncertainty about publisher locations - Use the preserved `lastSeen` timestamps to show when publishers were last active - Continue normal operation - tracking will resume automatically upon reconnection - + -## Automatic handling +## Automatic Handling The Asset Tracking SDK automatically: - Preserves publisher state information with `lastSeen` timestamps when connection is lost - Attempts reconnection using the underlying Ably SDK's retry logic with exponential backoff - Resumes normal tracking once connection is restored - Transitions back from the UNKNOWN state to normal operation seamlessly - + ## Prevention @@ -88,14 +88,18 @@ The Asset Tracking SDK automatically: - Use appropriate authentication token expiry times to minimize disconnections - Consider implementing offline caching for critical tracking data -## Related resources +## Related Errors + +• **[100004 - Subscriber Never Online](https://help.ably.io/error/100004)** + Occurs when the subscriber has never successfully connected, indicating initial connection issues rather than connection loss + +## Related Resources - [Asset Tracking Documentation](https://ably.com/docs/asset-tracking) -- [Connection State Management](https://ably.com/docs/realtime/connection) +- [Connection State Management](https://ably.com/docs/connect/states) - [Asset Tracking Android SDK](https://github.com/ably/ably-asset-tracking-android) -- Related error: [100004](https://help.ably.io/error/100004) - Subscriber has never been online -## Need further help? +## Need Further Help? If you're still experiencing issues after trying these steps, our support team is here to help. @@ -114,16 +118,19 @@ Our team will help you resolve this issue as quickly as possible. - + + + @@ -156,6 +163,6 @@ To improve this error code documentation: 1. First approach: Update editorial-notes.md in ably-os repository with specific guidance for error 100005 2. Regenerate: Run `./bin/ably-os errors document-error-codes 100005 --force` 3. For broader improvements: Review and update ably-os prompt templates -4. Context: See https://github.com/ably/ably-os/blob/main/docs/ERROR_COMMANDS_GUIDE.md +4. Context: See https://github.com/ably/ably-os/blob/5f4ba43/docs/ERROR_COMMANDS_GUIDE.md 5. Source repository: https://github.com/ably/ably-os --> \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/101000-space-name-missing.mdx b/src/pages/docs/platform/errors/codes/101000-space-name-missing.mdx index 83a1633d90..c22869a17e 100644 --- a/src/pages/docs/platform/errors/codes/101000-space-name-missing.mdx +++ b/src/pages/docs/platform/errors/codes/101000-space-name-missing.mdx @@ -1,13 +1,13 @@ - + - + # Error 101000: Space name missing @@ -39,21 +39,21 @@ You'll see this message: - Passing an empty string `""` to `spaces.get()` - Accidentally clearing a variable before use - String trimming resulting in empty value - + 2. **Null or undefined value** (35% of cases) - Variable not initialized before use - Missing parameter in function call - Async data not loaded yet - Destructuring from undefined object - + 3. **Wrong parameter type** (25% of cases) - Passing a number instead of a string - Passing an object or array - Type conversion issues - Template literal evaluation errors - + ## Resolution Steps @@ -72,7 +72,7 @@ You'll see this message: await spaces.get("chat-" + userId); await spaces.get(`user-${userId}-space`); ``` - + 2. **Validate input before calling** ```javascript @@ -92,7 +92,7 @@ You'll see this message: return spaces.get(trimmed); } ``` - + 3. **Handle dynamic space names** ```javascript @@ -110,7 +110,7 @@ You'll see this message: // Handle the error appropriately for your application } ``` - + 4. **TypeScript for compile-time safety** ```typescript @@ -128,7 +128,7 @@ You'll see this message: return await spaces.get(config.name); } ``` - + ## Automatic Handling @@ -197,7 +197,7 @@ try { console.error('Failed to join space:', error); } ``` - + ## Prevention @@ -233,6 +233,7 @@ This error has minimal performance impact as it: ## Related Resources - [Ably Spaces documentation](https://ably.com/docs/products/spaces) +- [Spaces homepage](https://ably.com/spaces) - [Spaces SDK GitHub repository](https://github.com/ably/spaces) - [Spaces SDK npm package](https://www.npmjs.com/package/@ably/spaces) - [Ably documentation](https://ably.com/docs) @@ -256,13 +257,13 @@ Our team will help you resolve this issue as quickly as possible. - - + + @@ -279,17 +280,17 @@ Our team will help you resolve this issue as quickly as possible. \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/101001-not-entered-space.mdx b/src/pages/docs/platform/errors/codes/101001-not-entered-space.mdx index b073857c7e..dd3c84d84b 100644 --- a/src/pages/docs/platform/errors/codes/101001-not-entered-space.mdx +++ b/src/pages/docs/platform/errors/codes/101001-not-entered-space.mdx @@ -1,11 +1,11 @@ - + @@ -38,17 +38,17 @@ You'll see this message: 1. **Not calling space.enter()** (90% of cases) - Attempting operations immediately after getting a space reference - Forgetting to enter the space in your initialization code - + 2. **Race conditions** (8% of cases) - Calling space operations before `enter()` completes - Not awaiting the enter operation - + 3. **Wrong space instance** (2% of cases) - Operating on a different space than the one entered - Creating multiple space instances accidentally - + ## Resolution Steps @@ -65,7 +65,7 @@ You'll see this message: // Now you can perform operations await space.cursors.set({ position: { x: 50, y: 50 } }); ``` - + 2. **Verify you've entered the space** ```javascript @@ -75,7 +75,7 @@ You'll see this message: await space.enter({ username: 'User Name' }); } ``` - + 3. **Handle the error gracefully** ```javascript @@ -92,12 +92,12 @@ You'll see this message: } } ``` - + ## Automatic Handling The Spaces SDK does not automatically enter spaces. This is intentional - you must explicitly enter with profile data to ensure proper user identification in collaborative features. - + ## Code Examples @@ -118,7 +118,7 @@ await space.enter({ await space.locations.set({ x: 100, y: 200 }); await space.cursors.set({ position: { x: 50, y: 50 } }); ``` - + ### Operations That Require Entry @@ -127,7 +127,7 @@ The following operations will throw error 101001 if you haven't entered the spac - **Space membership**: `space.leave()` - **Cursor management**: `cursors.set()` - **Location tracking**: `locations.set()` - + ## Prevention @@ -135,12 +135,12 @@ The following operations will throw error 101001 if you haven't entered the spac - Use async/await to ensure enter completes before other operations - Store the space instance to avoid creating duplicates - Include proper error handling for space operations - + ## Related Resources -- [Spaces documentation](https://ably.com/docs/spaces/space#enter) -- [Space.enter() API reference](https://ably.com/docs/spaces/space#enter) +- [Spaces documentation](https://ably.com/docs/spaces) +- [Spaces SDK GitHub repository](https://github.com/ably/spaces) ## Related Errors @@ -173,36 +173,38 @@ Our team will help you resolve this issue as quickly as possible. - - + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/101002-lock-request-already-exists.mdx b/src/pages/docs/platform/errors/codes/101002-lock-request-already-exists.mdx index 1b7b09d7d1..62f6ca2126 100644 --- a/src/pages/docs/platform/errors/codes/101002-lock-request-already-exists.mdx +++ b/src/pages/docs/platform/errors/codes/101002-lock-request-already-exists.mdx @@ -1,13 +1,13 @@ - + - + # Error 101002: Lock request already exists @@ -39,17 +39,19 @@ You'll see this exact message: - Calling `acquire()` multiple times without waiting for the first to complete - Attempting to acquire a lock that's already pending or locked by your connection - Race conditions in application code triggering duplicate lock requests - + - Event handlers or loops inadvertently calling acquire() repeatedly + 2. **Missing lock state management** (10% of cases) - Not tracking lock status in your application - Ignoring lock state change events - Not properly handling lock lifecycle - + - Missing debouncing on user-triggered lock requests + ## Resolution Steps -1. **Check current lock status** +1. **Check current lock status before acquiring** ```javascript // Get the lock instance for your component const lock = space.locks.get('component-id'); @@ -58,102 +60,151 @@ You'll see this exact message: if (lock.status === 'pending' || lock.status === 'locked') { // Wait for existing lock to resolve console.log('Lock already exists, waiting...'); + return; // Don't attempt to acquire again + } + + // Safe to acquire if status is 'unlocked' + if (lock.status === 'unlocked') { + const newLock = await lock.acquire(); } ``` - + -2. **Handle existing lock appropriately** - - If `status === 'pending'`: Wait for the lock request to complete - - If `status === 'locked'`: Either use the existing lock or release it first +2. **Handle existing lock appropriately based on state** + - If `status === 'pending'`: Wait for the lock request to complete - it will transition to either 'locked' or 'unlocked' + - If `status === 'locked'`: Either use the existing lock or release it first before acquiring again - If `status === 'unlocked'`: Safe to acquire a new lock - + 3. **Implement proper lock lifecycle management with React hooks** ```javascript // React example with proper lock handling - const { status, member, acquire, release } = useLock('component-id'); + import { useLock } from '@ably/spaces/react'; - const requestLock = async () => { - // Only acquire if not already locked or pending - if (status === 'unlocked') { - try { - const lock = await acquire(); - // Lock acquired successfully - console.log('Lock acquired'); - } catch (error) { - if (error.code === 101002) { - console.log('Lock request already exists'); - // Handle appropriately - wait for existing request + function EditableComponent({ componentId }) { + const { status, member, acquire, release } = useLock(componentId); + const [isRequesting, setIsRequesting] = useState(false); + + const requestLock = async () => { + // Prevent duplicate requests + if (isRequesting) return; + + // Only acquire if not already locked or pending + if (status === 'unlocked') { + setIsRequesting(true); + try { + const lock = await acquire(); + console.log('Lock acquired successfully'); + } catch (error) { + if (error.code === 101002) { + console.log('Lock request already exists'); + // Handle appropriately - wait for existing request + } + } finally { + setIsRequesting(false); } + } else { + console.log(`Cannot acquire - lock status is: ${status}`); } - } else { - console.log(`Cannot acquire - lock status is: ${status}`); - } - }; + }; + + return ( + + ); + } ``` - + -4. **Subscribe to lock state changes** +4. **Subscribe to lock state changes for coordination** ```javascript // Monitor lock state changes to coordinate requests lock.subscribe('update', (lockUpdate) => { console.log(`Lock status changed to: ${lockUpdate.status}`); + if (lockUpdate.status === 'unlocked') { // Now safe to acquire if needed + // But check if you still need the lock + } else if (lockUpdate.status === 'locked' && lockUpdate.member.connectionId === self.connectionId) { + // You have the lock - enable editing + enableEditing(); + } else if (lockUpdate.status === 'locked') { + // Someone else has the lock - disable editing + disableEditing(); } }); ``` - + 5. **Use attributes for better lock management** ```javascript - // Include metadata when acquiring locks + // Include metadata when acquiring locks for better tracking const lock = await acquire({ attributes: { componentId: 'editor-field-1', userId: currentUser.id, - timestamp: Date.now() + timestamp: Date.now(), + action: 'editing' // what the lock is for } }); + + // These attributes are available to all members + // helping coordinate who is doing what ``` ## Automatic Handling -The Ably Spaces SDK does not automatically retry lock acquisitions for this error. Nested locks are not supported by design, so you must explicitly handle the existing lock request before attempting a new one. - +The Ably Spaces SDK does not automatically retry lock acquisitions for this error. Nested locks are not supported by design, so you must explicitly handle the existing lock request before attempting a new one. The error is thrown client-side before any server communication occurs. + ## Prevention -- **Always check lock status** before calling `acquire()` +- **Always check lock status** before calling `acquire()` - only proceed if status is 'unlocked' - **Implement state tracking** to know when you have pending or active locks -- **Use lock events** to coordinate multiple lock requests +- **Use lock events** to coordinate multiple lock requests and react to state changes - **Release locks promptly** when no longer needed to avoid conflicts - **Avoid duplicate calls** to `acquire()` in event handlers or loops -- **Implement debouncing** for user-triggered lock requests -- **Use React hooks properly** to manage lock state in components - +- **Implement debouncing** for user-triggered lock requests to prevent rapid clicking +- **Use React hooks properly** to manage lock state in components with proper cleanup +- **Track request state** with a flag to prevent concurrent acquisition attempts + + +## Performance Impact + +This error prevents lock acquisition but doesn't affect: +- Existing space connections +- Other members' ability to acquire locks +- Message delivery or presence updates +- Cursor tracking or avatar stacks + +The error is thrown immediately without network round-trip, minimizing performance impact. ## Related Errors • **[101000 - Space Name Missing](https://help.ably.io/error/101000)** - Invalid or missing space name when creating a space instance + Invalid or missing space name when creating a space instance - must provide valid space name • **[101001 - Not Entered Space](https://help.ably.io/error/101001)** - Must enter the space before attempting to acquire locks + Must enter the space before attempting to acquire locks - call space.enter() first • **[101003 - Lock is Locked](https://help.ably.io/error/101003)** Lock is already held by another member - occurs when trying to acquire a lock held by someone else • **[101004 - Lock Invalidated](https://help.ably.io/error/101004)** - Your lock request was invalidated by another member's acquisition + Your lock request was invalidated by another member's acquisition - handle optimistic locking conflicts ## Related Resources - [Ably Spaces Locking Documentation](https://ably.com/docs/spaces/locking) -- [Component Locking States](https://ably.com/docs/spaces/locking#states) +- [Component Locking States](https://ably.com/docs/products/spaces) - [Spaces React Hooks](https://ably.com/docs/spaces/react) -- [Interactive Locking Example](https://ably.com/examples/spaces-component-locking) +- [Interactive Locking Example](https://ably.com/examples/component-locking) +- [Spaces SDK on GitHub](https://github.com/ably/spaces) ## Need Further Help? @@ -175,46 +226,49 @@ Our team will help you resolve this issue as quickly as possible. - - + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/101003-lock-is-locked.mdx b/src/pages/docs/platform/errors/codes/101003-lock-is-locked.mdx index ef16ef5913..fc29a7652d 100644 --- a/src/pages/docs/platform/errors/codes/101003-lock-is-locked.mdx +++ b/src/pages/docs/platform/errors/codes/101003-lock-is-locked.mdx @@ -1,31 +1,35 @@ - + - + # Error 101003: Lock is locked ## What Happened? + The component lock you requested is currently held by another user, and your request did not take priority. ## Quick Reference + | Error Code | HTTP Status | Category | Retryable | |------------|-------------|----------|-----------| | 101003 | 400 | Locking/Conflict (Spaces) | Yes - lock will become available | ## Quick Fix + - This is normal behavior when multiple users try to lock the same component - Subscribe to lock update events to know when the lock becomes available - Implement retry logic with appropriate backoff ## Error Messages + You'll see this in the lock response: - "lock is currently locked" @@ -37,19 +41,19 @@ The error is assigned to the `reason` property when lock acquisition fails. - Multiple users trying to edit the same component simultaneously - Normal behavior in collaborative applications - Part of the distributed locking mechanism design - + 2. **Network timing and race conditions** - Lock requests arriving out of order due to network latency - Presence system delays affecting lock state synchronization - Temporary network disconnections causing lock state mismatches - + 3. **Priority resolution conflicts** - Timestamp-based priority system determines lock ownership - Connection ID used as tiebreaker when timestamps match - Existing lock holder maintains priority over new requests - + ## Resolution Steps @@ -57,42 +61,46 @@ The error is assigned to the `reason` property when lock acquisition fails. - This is not an error but normal lock contention - Design your UI to gracefully handle locked components - Show visual feedback about who holds the lock - + 2. **Subscribe to lock update events** - Monitor when the lock becomes available - Automatically retry when the lock is released - Implement a subscription before attempting lock acquisition - + 3. **Implement proper retry strategy** - Use exponential backoff with jitter for retries - Set a maximum retry limit to prevent infinite loops - Consider offering manual retry option to users - + 4. **Provide comprehensive visual feedback** - Show who currently holds the lock - Display queue position if applicable - Notify users when locks become available - Consider showing estimated wait time - + ## Automatic Handling + The Spaces SDK does not automatically retry lock acquisition. Your application must implement appropriate retry logic based on your specific use case and user experience requirements. - + ## Prevention + - Consider using optimistic UI updates where appropriate - Design your collaborative features to minimize lock contention - Implement clear visual indicators of component availability - Use granular locking (lock smaller components when possible) - Consider read-only modes for viewing without locking - + ## Related Resources + - [Ably Spaces Component Locking documentation](https://ably.com/docs/spaces/locking) -- [Ably Spaces SDK documentation](https://ably.com/docs/spaces) +- [Ably Spaces SDK documentation](https://ably.com/docs/products/spaces) +- [Ably Spaces product page](https://ably.com/spaces) ## Related Errors @@ -105,6 +113,9 @@ The Spaces SDK does not automatically retry lock acquisition. Your application m • **[101002 - Lock Invalidated](https://help.ably.io/error/101002)** Lock was invalidated by another request with higher priority +• **[101004 - Lock Pending](https://help.ably.io/error/101004)** + Lock request is still being processed and waiting for resolution + ## Need Further Help? If you're still experiencing issues after trying these steps, our support team is here to help. @@ -125,20 +136,20 @@ Our team will help you resolve this issue as quickly as possible. - - + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/101004-lock-invalidated.mdx b/src/pages/docs/platform/errors/codes/101004-lock-invalidated.mdx index a107a79d07..bf2d07fe96 100644 --- a/src/pages/docs/platform/errors/codes/101004-lock-invalidated.mdx +++ b/src/pages/docs/platform/errors/codes/101004-lock-invalidated.mdx @@ -1,14 +1,13 @@ - + - + # Error 101004: Lock invalidated @@ -42,7 +41,7 @@ You'll see this in the lock's `reason` property when it transitions to `unlocked - Multiple members attempting to lock the same component simultaneously - The member with the earlier timestamp gets priority - When timestamps are identical, lower connection ID wins - + 2. **Network latency differences** (8% of cases) - Members with better network conditions may submit requests with earlier timestamps @@ -53,7 +52,7 @@ You'll see this in the lock's `reason` property when it transitions to `unlocked - React components not properly cleaning up lock subscriptions - Lock events firing after component unmounting - Missing cleanup in useEffect return functions - + ## Resolution Steps @@ -67,7 +66,7 @@ You'll see this in the lock's `reason` property when it transitions to `unlocked } }); ``` - + 2. **Implement graceful handling** - Notify the user that another member has taken control @@ -86,14 +85,14 @@ You'll see this in the lock's `reason` property when it transitions to `unlocked }; }, []); ``` - + 4. **Understanding lock priority** - Earlier timestamps always win in conflict resolution - When timestamps are identical, lower connection IDs win - This ensures deterministic conflict resolution across all clients - The algorithm guarantees consistent results regardless of network conditions - + ## Automatic Handling @@ -102,7 +101,7 @@ Unlike thrown exceptions, error 101004 is assigned to the lock's `reason` proper - React to lock state changes through event subscriptions - Handle invalidation gracefully without disrupting user experience - Maintain application state consistency during conflicts - + ## Code Examples @@ -147,7 +146,7 @@ function releaseLock(lock, subscription) { return lock.release(); } ``` - + ### React Hook Pattern for Lock Management @@ -186,7 +185,7 @@ function useComponentLock(componentId) { return { lockStatus, lockHolder }; } ``` - + ## Prevention @@ -206,15 +205,14 @@ Lock invalidation has minimal performance impact: ## Related Resources -- [Spaces Locking Documentation](https://ably.com/docs/spaces/locking) -- [Spaces React Hooks](https://ably.com/docs/spaces/react) -- [Component Locking Guide](https://ably.com/docs/spaces/locking#handling-lock-conflicts) -- [Spaces SDK Reference](https://ably.com/docs/spaces) +- [Spaces Documentation](https://ably.com/docs) +- [Spaces SDK Reference](https://github.com/ably/spaces) +- [Ably Support](https://ably.com/support) ## Related Errors -• **[101002 - Lock is already held](https://help.ably.io/error/101002)** - Occurs when attempting to acquire a lock that another member currently holds +• **[101002 - Lock request exists](https://help.ably.io/error/101002)** + Occurs when attempting to acquire a lock while another request is pending or locked • **[101003 - Lock was released](https://help.ably.io/error/101003)** The lock was explicitly released by the holding member or expired @@ -245,15 +243,15 @@ Our team will help you resolve this issue as quickly as possible. - - + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/10200-unrecognized-error.mdx b/src/pages/docs/platform/errors/codes/10200-unrecognized-error.mdx index 8f84acdfa4..029fd44081 100644 --- a/src/pages/docs/platform/errors/codes/10200-unrecognized-error.mdx +++ b/src/pages/docs/platform/errors/codes/10200-unrecognized-error.mdx @@ -1,13 +1,13 @@ - + - + # Error 10200: Unrecognized error code @@ -39,25 +39,29 @@ This error code may appear due to: 1. **Parsing or logging issues** - Error extraction tools misrepresenting other error codes - Logging systems truncating longer error codes + 2. **Possible confusion with error 102000** - Chat room name validation errors - If working with Ably Chat, check room name format + ## Resolution Steps 1. **Verify the actual error code** - Check your logs for the complete error code - Look for 6-digit error codes that may have been truncated + 2. **If using Ably Chat** - You may be encountering error 102000 (room name validation) - Ensure room names don't start with ':', ',', '[' or spaces - Ensure room names don't contain '::$' + 3. **Update your SDK** - Ensure you're using the latest version of your Ably SDK - - Check the [Ably SDK downloads page](https://ably.com/download) for updates + - Check available SDKs and versions in the Ably documentation ## Automatic Handling @@ -65,23 +69,31 @@ This error code is not recognized by Ably SDKs and will not be automatically han ## Need Further Help? -This error code has limited documentation available. If you encounter this error, please contact Ably support at https://ably.com/support with: -- The full error message -- What action triggered the error +If you're still experiencing issues after trying these steps, our support team is here to help. + +**Contact Ably Support**: https://ably.com/support + +When contacting support, please provide: - Your account ID and app ID -- The exact error code you're seeing (including all digits) +- The full error message including error code 10200 +- Steps to reproduce the issue +- Any relevant code snippets (without sensitive credentials) - The SDK and version you're using -Our support team will help you resolve this issue as quickly as possible. +Our team will help you resolve this issue as quickly as possible. + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/102100-room-discontinuity.mdx b/src/pages/docs/platform/errors/codes/102100-room-discontinuity.mdx index 067a30c74f..2656a29686 100644 --- a/src/pages/docs/platform/errors/codes/102100-room-discontinuity.mdx +++ b/src/pages/docs/platform/errors/codes/102100-room-discontinuity.mdx @@ -1,20 +1,20 @@ - + - + # Error 102100: Room discontinuity ## What Happened -Your chat room has experienced a discontinuity that requires the application to re-synchronize its state with the server. +Your chat room has experienced a discontinuity where the connection was re-established but previous state could not be preserved, requiring your application to re-synchronize with the server. ## Quick Reference @@ -24,139 +24,285 @@ Your chat room has experienced a discontinuity that requires the application to ## Quick Fix -- The Chat SDK automatically emits discontinuity events to your application -- Re-attach the room to restore connectivity -- Synchronize missed messages using the history API +- Listen for discontinuity events in your application +- Re-attach the affected room when this error occurs +- Retrieve missed messages using the history API +- Update your UI to reflect the synchronized state ## Error Messages -You may see one of these messages: +You may encounter one of these messages: - "discontinuity detected" - "Discontinuity detected, [original error message]" - "The room has experienced a discontinuity" +The specific message varies by SDK but all indicate the same underlying discontinuity condition. + ## Common Causes -1. **Extended disconnection** (most common) - - Network interruption lasting beyond 2 minutes +1. **Extended network disconnection** (most common) + - Connection lost for more than 2 minutes - Exceeds automatic recovery window - - Channel state cannot be preserved - + - Channel state cannot be preserved across reconnection + 2. **Server-side connection termination** - Load balancing operations - - Server maintenance or updates + - Server maintenance or rolling updates - Connection shedding for resource management - + - Regional failover events + 3. **Channel state loss** - Channel re-attaches without the `resumed` flag - Previous message continuity cannot be guaranteed + - Presence set may be outdated - Requires full state resynchronization - + ## Resolution Steps -1. **Listen for discontinuity events** +1. **Subscribe to discontinuity events** ```javascript // JavaScript/TypeScript room.on('discontinuity', (error) => { - // Handle error code 102100 - handleDiscontinuity(); + if (error.code === 102100) { + handleDiscontinuity(); + } }); ``` - + + ```kotlin + // Kotlin/Android + room.onDiscontinuity { error -> + if (error.code == 102100) { + handleDiscontinuity() + } + } + ``` + + ```swift + // Swift/iOS + room.onDiscontinuity { event in + if event.error.code == 102100 { + handleDiscontinuity() + } + } + ``` + 2. **Re-attach the affected room** - - Call the room's attach method - - Wait for successful attachment - - This restores the connection to all room features - + - Call the room's `attach()` method + - Wait for successful attachment confirmation + - This restores connectivity to all room features (messages, presence, typing indicators, reactions) + 3. **Synchronize room state** - - Retrieve missed messages using `getPreviousMessages()` or history API - - Update your UI with the latest message state - - Re-synchronize presence information if needed - + - Retrieve missed messages using `getPreviousMessages()` or the history API + - Update your local message list with the fetched history + - Re-synchronize presence information if your app uses it + - Reset any typing indicators or ephemeral state + -4. **Notify users of recovery** +4. **Update your UI appropriately** - Display a reconnection indicator during recovery - - Clear the indicator once synchronization is complete - - Consider queuing outgoing messages during recovery - + - Queue outgoing messages while recovering (or inform users they're temporarily offline) + - Clear the reconnection indicator once synchronization completes + - Consider showing a subtle notification that the room was reconnected + ## Automatic Handling The Ably Chat SDK automatically: - Detects discontinuities when channels re-attach without preserving state -- Emits discontinuity events to your application -- Handles transient disconnections (under 2 minutes) without emitting this error -- Preserves message history that can be retrieved after recovery - +- Emits discontinuity events to your application for handling +- Manages transient disconnections (under 2 minutes) transparently without emitting this error +- Preserves message history on the server that can be retrieved after recovery +- Tracks the `hasAttachedOnce` flag to differentiate initial connection failures from discontinuities + ## Code Examples -### JavaScript/TypeScript +### Complete Recovery Implementation (JavaScript/TypeScript) ```javascript +// Set up discontinuity handler room.on('discontinuity', async (error) => { if (error.code === 102100) { - // Show reconnecting indicator - showReconnectingUI(); + console.log('Room discontinuity detected, recovering...'); - // Re-attach the room - await room.attach(); + // Show reconnecting UI + showReconnectingIndicator(); - // Sync missed messages - const history = await room.messages.getPreviousMessages({ limit: 100 }); - updateMessageList(history); - - // Clear reconnecting indicator - hideReconnectingUI(); + try { + // Re-attach the room + await room.attach(); + + // Fetch missed messages + const history = await room.messages.getPreviousMessages({ + limit: 100 + }); + + // Update message list (reverse to get chronological order) + const missedMessages = history.items.reverse(); + updateMessageList(missedMessages); + + // Re-sync presence if used + const members = await room.presence.get(); + updatePresenceList(members); + + // Clear reconnecting indicator + hideReconnectingIndicator(); + showToast('Room reconnected successfully'); + + } catch (recoveryError) { + console.error('Failed to recover from discontinuity:', recoveryError); + showErrorMessage('Unable to reconnect. Please refresh the page.'); + } } }); ``` - + -### Kotlin/Android +### Robust Recovery with Message Queuing (Kotlin/Android) ```kotlin -room.onDiscontinuity { error -> - if (error.code == 102100) { - // Handle discontinuity - room.attach() - syncLatestMessages() - } +class ChatRoomManager { + private val messageQueue = mutableListOf() + private var isRecovering = false + + fun setupDiscontinuityHandler(room: Room) { + room.onDiscontinuity { error -> + if (error.code == 102100) { + handleDiscontinuity(room) + } + } + } + + private suspend fun handleDiscontinuity(room: Room) { + isRecovering = true + showReconnectingUI() + + try { + // Re-attach room + room.attach() + + // Sync messages + val history = room.messages.getPreviousMessages(100) + updateMessageList(history) + + // Process queued messages + messageQueue.forEach { pending -> + room.messages.send(pending.text) + } + messageQueue.clear() + + isRecovering = false + hideReconnectingUI() + + } catch (e: Exception) { + showError("Failed to reconnect: ${e.message}") + } + } + + fun sendMessage(text: String) { + if (isRecovering) { + messageQueue.add(PendingMessage(text)) + showToast("Message queued") + } else { + room.messages.send(text) + } + } } ``` - + -### Swift/iOS +### Graceful Recovery with State Management (Swift/iOS) ```swift -room.onDiscontinuity { event in - if event.error.code == 102100 { - // Recover room state - try await room.attach() - try await synchronizeRoomState() - } +class ChatRoomViewModel: ObservableObject { + @Published var connectionState = ConnectionState.connected + private var room: Room + + func setupDiscontinuityHandler() { + room.onDiscontinuity { [weak self] event in + guard event.error.code == 102100 else { return } + + Task { + await self?.recoverFromDiscontinuity() + } + } + } + + @MainActor + private func recoverFromDiscontinuity() async { + connectionState = .recovering + + do { + // Re-attach room + try await room.attach() + + // Sync latest messages + let history = try await room.messages.getPreviousMessages( + options: .init(limit: 100) + ) + + // Update UI with synced messages + await MainActor.run { + self.messages = history.items.reversed() + self.connectionState = .connected + } + + // Show success notification + showNotification("Chat reconnected") + + } catch { + connectionState = .disconnected + showError("Unable to reconnect: \(error.localizedDescription)") + } + } } ``` - + ## Prevention -While discontinuities cannot be completely prevented due to network conditions, you can minimize their impact: +While network discontinuities cannot be completely prevented, you can minimize their impact: + +- **Implement robust event handlers**: Set up discontinuity listeners immediately after creating rooms +- **Design for resilience**: Build your UI to gracefully handle temporary disconnections +- **Cache recent messages**: Store recent messages locally for immediate display during recovery +- **Use visual indicators**: Keep users informed with connection status badges or banners +- **Consider message queuing**: Queue outgoing messages during recovery rather than failing immediately +- **Test recovery flows**: Regularly test discontinuity scenarios in development + + +## Performance Impact -- Implement robust discontinuity event handlers from the start -- Design your UI to gracefully handle temporary disconnections -- Cache recent messages locally for immediate display during recovery -- Use visual indicators to keep users informed of connection status - +When this error occurs: +- **Message delivery**: Temporarily interrupted until re-attachment +- **Presence accuracy**: May show outdated member list until synchronized +- **Typing indicators**: Will be reset and need to be re-established +- **Reactions**: Ephemeral reactions may be lost during the discontinuity period +- **History retrieval**: Available immediately after re-attachment ## Related Resources -- [Ably Chat SDK documentation](https://ably.com/docs/products/chat) -- [Connection state management](https://ably.com/docs/connect/states) -- [Message history and recovery](https://ably.com/docs/storage-history/history) -- Related errors: [102101](./102101-room-failed.mdx) (Room failed), [102106](./102106-room-released.mdx) (Room released) +- [Ably Chat documentation](https://ably.com/docs/chat) +- [Connection state management](https://ably.com/docs/connect) +- [Message history](https://ably.com/docs/storage-history) +- [Chat SDK on GitHub](https://github.com/ably/ably-chat-js) + +## Related Errors + +• **[102101 - Room Failed](https://help.ably.io/error/102101)** + Room entered a failed state requiring manual recovery or recreation + +• **[102106 - Room Released](https://help.ably.io/error/102106)** + Operation attempted on a room that has been released from memory + +• **[102103 - Room Is Released](https://help.ably.io/error/102103)** + Room has been fully released and cannot be used + +• **[102102 - Room Is Releasing](https://help.ably.io/error/102102)** + Operation attempted while room is in the process of being released ## Need Further Help? @@ -177,39 +323,43 @@ Our team will help you resolve this issue as quickly as possible. - + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/102101-room-in-failed-state.mdx b/src/pages/docs/platform/errors/codes/102101-room-in-failed-state.mdx index 5fd9489299..3d8bfeb1b8 100644 --- a/src/pages/docs/platform/errors/codes/102101-room-in-failed-state.mdx +++ b/src/pages/docs/platform/errors/codes/102101-room-in-failed-state.mdx @@ -1,20 +1,20 @@ - + - + # Error 102101: Room in failed state ## What Happened -The Chat room you're trying to use has entered a failed state and cannot perform any operations. +The Chat room you're trying to use has entered a failed state and cannot perform any operations until it's released and recreated. ## Quick Reference @@ -27,6 +27,7 @@ The Chat room you're trying to use has entered a failed state and cannot perform - Release the failed room using `room.release()` - Create a new room instance with `chat.rooms.get()` - Monitor room status to detect failures early +- Investigate underlying channel failures that caused the room failure ## Error Messages @@ -37,16 +38,24 @@ You may see one of these messages: ## Common Causes -1. **Underlying channel failures** (90% of cases) - - Network connectivity issues causing channel disconnections - - Authentication failures on room channels - - Server-side errors affecting room channels - +1. **Underlying channel failures** (85% of cases) + - Network connectivity issues causing persistent channel disconnections + - Authentication failures on the underlying room channels + - Server-side errors affecting room channels that cannot be recovered + - Channel entering terminal failed state after multiple retry attempts + 2. **Irrecoverable room errors** (10% of cases) - - Room entered terminal failed state after multiple retry attempts + - Room entered terminal failed state after exhausting retry attempts - Critical errors during room initialization or attachment - + - Cascading failures from dependent channel operations + + +3. **Room lifecycle violations** (5% of cases) + - Attempting operations during failed state transitions + - Race conditions in room state management + - Atomic operation violations during state changes + ## Resolution Steps @@ -56,56 +65,82 @@ You may see one of these messages: console.log('Room has failed and must be recreated'); } ``` - + 2. **Release the failed room** ```javascript await room.release(); ``` - + 3. **Create a new room instance** ```javascript const newRoom = await chat.rooms.get('room-id', { // Your room options + reactions: { enabled: true }, + typing: { timeoutMs: 10000 } }); await newRoom.attach(); ``` - + 4. **Monitor room status to prevent future failures** ```javascript room.on('status', (status) => { if (status === RoomStatus.Failed) { - // Handle room failure + // Handle room failure immediately + console.error('Room failed - releasing and recreating'); handleRoomFailure(); } }); ``` - + + +5. **Investigate root cause** + - Check the underlying channel states for failure reasons + - Review connection logs for authentication or network issues + - Monitor for patterns in room failures + ## Automatic Handling Ably Chat SDKs do not automatically recover from room failed states. When a room enters the failed state: -- All operations on the room are blocked -- The room remains in failed state permanently +- All operations on the room are permanently blocked +- The room remains in failed state until explicitly released - You must manually release and recreate the room - +- The SDK enforces CHA-RL2d specification requirements for state validation + ## Prevention -- **Monitor connection health**: Track underlying Ably connection status -- **Handle channel errors gracefully**: Respond to channel-level errors before they cause room failure +- **Monitor connection health**: Track underlying Ably connection status continuously +- **Handle channel errors gracefully**: Respond to channel-level errors before they cascade to room failure - **Implement room status monitoring**: React to room status changes proactively - **Use appropriate error handling**: Catch and handle room lifecycle errors properly - +- **Set reasonable timeout values**: Configure appropriate timeouts for your use case +- **Implement retry strategies**: Have a plan for handling transient failures before they become terminal + ## Related Resources - [Ably Chat documentation](https://ably.com/docs/chat) - [Room lifecycle management](https://ably.com/docs/chat/rooms) - [Connection state handling](https://ably.com/docs/connect) -- Related errors: Room lifecycle errors in the 102xxx range +- [Chat SDK setup guide](https://ably.com/docs/chat/setup) + +## Related Errors + +• **[80000 - Connection Failed](https://help.ably.io/error/80000)** + Underlying connection failures that can cascade to room failures + +• **[80002 - Connection Suspended](https://help.ably.io/error/80002)** + Connection suspension that may impact room operations + +• **[90000 - Channel Operation Failed](https://help.ably.io/error/90000)** + Channel-level failures that can trigger room failure states + +• **[102102 - Room Released](https://help.ably.io/error/102102)** + Related room lifecycle error for released room state ## Need Further Help? @@ -126,43 +161,50 @@ Our team will help you resolve this issue as quickly as possible. - + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/102102-room-is-releasing.mdx b/src/pages/docs/platform/errors/codes/102102-room-is-releasing.mdx index 0bd7682f63..ed3cc32f9a 100644 --- a/src/pages/docs/platform/errors/codes/102102-room-is-releasing.mdx +++ b/src/pages/docs/platform/errors/codes/102102-room-is-releasing.mdx @@ -1,16 +1,16 @@ - + - + -# Error 102102: Room is releasing +# Error 102102: Room is Releasing ## What Happened? @@ -31,7 +31,7 @@ You attempted to perform an operation on a chat room while it's in the process o ## Error Messages You may see one of these messages: -- "cannot [operation] room, room is currently releasing" (JavaScript) +- "cannot [operation] room, room is currently releasing" (JavaScript/TypeScript) - "Cannot perform operation because the room is in a releasing state" (Swift) The `[operation]` placeholder shows the specific action you attempted (attach, detach, presence, etc.). @@ -42,23 +42,25 @@ The `[operation]` placeholder shows the specific action you attempted (attach, d - Attempting to attach immediately after initiating release - Trying to use a room that's being cleaned up - Not waiting for release completion - + 2. **Improper state management** (15% of cases) - Application not tracking room lifecycle correctly - Missing status checks before operations - Concurrent operations on the same room - + 3. **Race conditions** (5% of cases) - Multiple parts of application accessing room during release - Asynchronous operations overlapping with release - + - Parallel operations not coordinated properly + ## Resolution Steps 1. **Check room status before operations** - + + Verify the room state before attempting any operations: ```javascript // ✅ Correct: Check status first if (room.status !== 'releasing' && room.status !== 'released') { @@ -68,10 +70,10 @@ The `[operation]` placeholder shows the specific action you attempted (attach, d // ❌ Wrong: Operating without checking await room.attach(); // May throw 102102 ``` - + 2. **Wait for release to complete** - + Listen for status changes and wait for the room to be fully released: ```javascript room.on('status', (status) => { @@ -81,10 +83,10 @@ The `[operation]` placeholder shows the specific action you attempted (attach, d } }); ``` - + 3. **Create a new room instance** - + Instead of waiting, immediately create a fresh room instance: ```javascript // Release old room @@ -94,35 +96,71 @@ The `[operation]` placeholder shows the specific action you attempted (attach, d const newRoom = chat.rooms.get(roomId); await newRoom.attach(); ``` - + 4. **Implement proper lifecycle management** - + Ensure graceful shutdown sequence: - Complete all pending operations - Initiate release - Wait for release completion - Only then create new instances if needed +5. **Queue operations for later execution** + + Buffer operations during release and execute after completion: + ```javascript + const pendingOperations = []; + + room.on('status', (status) => { + if (status === 'attached') { + // Execute queued operations + pendingOperations.forEach(op => op()); + pendingOperations.length = 0; + } + }); + ``` + ## Automatic Handling -The Ably Chat SDKs enforce this validation to prevent race conditions and ensure data consistency. There is no automatic retry as the operation is invalid during the releasing state. - +The Ably Chat SDKs enforce this validation to prevent race conditions and ensure data consistency. This is a protective mechanism implementing the CHA-RL1b and CHA-RL2b specifications for room lifecycle management. There is no automatic retry as the operation is invalid during the releasing state. + ## Prevention -- Always check room status before performing operations -- Implement proper state tracking in your application -- Use event listeners to monitor room lifecycle changes -- Avoid rapid create/release cycles on the same room - +- **Always check room status** before performing operations +- **Implement proper state tracking** in your application +- **Use event listeners** to monitor room lifecycle changes +- **Avoid rapid create/release cycles** on the same room +- **Coordinate parallel operations** to prevent conflicts +- **Handle cleanup gracefully** with proper sequencing + + +## Performance Impact + +This error indicates a transient state that typically resolves quickly. The release process usually completes within milliseconds to seconds, depending on network conditions and the number of active connections to the room. The error itself has minimal performance impact as it's a client-side validation that prevents invalid operations. + + +## Related Errors + +• **[102101 - Room is Released](https://help.ably.io/error/102101)** + Occurs when attempting operations on a room that has completed release and cannot be used anymore + +• **[102103 - Room is Failed](https://help.ably.io/error/102103)** + Room has entered a failed state due to an unrecoverable error and requires recreation + +• **[102104 - Room is Detached](https://help.ably.io/error/102104)** + Room is detached from underlying channels and needs reattachment before use + ## Related Resources - [Ably Chat Documentation](https://ably.com/docs/chat) - [Chat Rooms Guide](https://ably.com/docs/chat/rooms) -- Related errors: [102101](./102101-room-is-released.mdx) (Room is released), [102103](./102103-room-is-failed.mdx) (Room is failed) - +- [Chat SDK GitHub - JavaScript](https://github.com/ably/ably-chat-js) +- [Chat SDK GitHub - Swift](https://github.com/ably/ably-chat-swift) +- [Chat SDK Specification](https://github.com/ably/specification/tree/main/textile/chat) + ## Need Further Help? @@ -143,50 +181,59 @@ Our team will help you resolve this issue as quickly as possible. - + + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/102103-room-is-released.mdx b/src/pages/docs/platform/errors/codes/102103-room-is-released.mdx index 225b520505..5c356d4e28 100644 --- a/src/pages/docs/platform/errors/codes/102103-room-is-released.mdx +++ b/src/pages/docs/platform/errors/codes/102103-room-is-released.mdx @@ -1,20 +1,20 @@ - + - + # Error 102103: Room is released ## What Happened -You attempted to perform an operation on a Chat room that has already been released and deallocated. +You attempted to perform an operation on a Chat room that has already been released and its resources deallocated. ## Quick Reference @@ -25,119 +25,297 @@ You attempted to perform an operation on a Chat room that has already been relea ## Quick Fix - Get a new room instance using `rooms.get(roomId)` -- Update your references to point to the new room -- Avoid caching room instances that might outlive their lifecycle +- Update all references to use the new room instance +- Ensure your application handles room lifecycle events properly ## Error Messages -You may see one of these messages: -- "cannot {operation} room, room is released" (JavaScript) -- "unable to attach room; room is released" (Kotlin/Android) -- "unable to detach room; room is released" (Kotlin/Android) -- "Cannot perform operation because the room is in a released state" (Swift/iOS) +You may see one of these messages depending on your SDK and the operation attempted: + +**JavaScript/TypeScript:** +- "cannot {operation} room, room is released" - where {operation} could be: + - `attach` - when trying to attach to the room + - `detach` - when trying to detach from the room + - `send` - when trying to send a message + - `subscribe` - when trying to subscribe to events + - Any other room operation + +**Kotlin/Android:** +- "unable to attach room; room is released" - when calling `room.attach()` +- "unable to detach room; room is released" - when calling `room.detach()` + +**Swift/iOS:** +- "Cannot perform operation because the room is in a released state" - for any room operation including presence operations ## Common Causes 1. **Reusing released room references** (80% of cases) - Attempting to use a room after calling `release()` - - Holding onto room references after the room lifecycle ends + - Holding onto stale room references after room lifecycle ends - Not updating references after room recreation - + - Storing room instances in global state or caches + -2. **Race conditions** (15% of cases) - - Operations attempted during or after room release - - Asynchronous code not properly synchronized with room lifecycle - - Event handlers firing after room release - +2. **Race conditions in asynchronous code** (15% of cases) + - Operations attempted during or immediately after room release + - Event handlers firing after room has been released + - Asynchronous operations not properly synchronized with room lifecycle + - Promises or callbacks executing after component unmount + 3. **Improper lifecycle management** (5% of cases) - - Not handling room lifecycle events properly - Missing cleanup in component unmount/destroy handlers - + - Not properly handling room state transitions + - Caching room instances beyond their intended lifecycle + - Memory leaks from retained references + ## Resolution Steps -1. **Get a new room instance** +1. **Get a fresh room instance** ```javascript // JavaScript/TypeScript - const newRoom = await chat.rooms.get(roomId); - + const newRoom = await chat.rooms.get(roomId, { + // Optional: specify room options + typing: { timeoutMs: 10000 }, + reactions: { subscribe: true } + }); + await newRoom.attach(); + ``` + + ```kotlin // Kotlin/Android - val newRoom = chat.rooms.get(roomId) - + val newRoom = chat.rooms.get( + roomId = roomId, + options = RoomOptions( + typing = TypingOptions(timeoutMs = 10000), + reactions = RoomReactionsOptions() + ) + ) + newRoom.attach() + ``` + + ```swift // Swift/iOS - let newRoom = try await chat.rooms.get(roomId: roomId) + let newRoom = try await chat.rooms.get( + roomId: roomId, + options: RoomOptions( + typing: TypingOptions(timeoutMs: 10000), + reactions: RoomReactionsOptions() + ) + ) + try await newRoom.attach() ``` - + -2. **Update all references** - - Replace any stored references with the new room instance - - Update event listeners to use the new room - - Ensure UI components reference the updated room +2. **Update all existing references** + - Replace stored room references with the new instance + - Update event listener registrations + - Refresh UI components that reference the room + - Update any cached room instances in your state management + - Notify dependent components of the room change 3. **Implement proper lifecycle management** ```javascript - // Example: React component with proper cleanup + // React example with comprehensive cleanup useEffect(() => { let room; + let isActive = true; async function setupRoom() { - room = await chat.rooms.get(roomId); - await room.attach(); - // Setup subscriptions + try { + room = await chat.rooms.get(roomId); + if (!isActive) return; // Component unmounted + + await room.attach(); + + // Setup subscriptions with cleanup tracking + const unsubscribeMessages = room.messages.subscribe((message) => { + if (isActive) { + handleMessage(message); + } + }); + + const unsubscribeTyping = room.typing.subscribe((event) => { + if (isActive) { + handleTypingEvent(event); + } + }); + + // Store unsubscribe functions for cleanup + return () => { + unsubscribeMessages(); + unsubscribeTyping(); + }; + } catch (error) { + if (error.code === 102103) { + // Room was released, retry with new instance + console.log('Room was released, retrying...'); + if (isActive) { + setTimeout(setupRoom, 1000); + } + } else { + console.error('Room setup failed:', error); + } + } } - setupRoom(); + const cleanup = setupRoom(); return () => { - // Cleanup on unmount - if (room) { + isActive = false; + cleanup?.then(unsubscribe => unsubscribe?.()); + if (room && room.status !== 'released') { room.release(); } }; }, [roomId]); ``` - + -4. **Handle room lifecycle states** - - Monitor room status before operations - - Implement appropriate error handling - - Consider implementing reconnection logic for your use case +4. **Handle room lifecycle states properly** + ```javascript + // Monitor room status before operations + if (room.status === 'released') { + // Get new room instance + room = await chat.rooms.get(roomId); + await room.attach(); + } + + // Listen for lifecycle changes + room.on('status', (change) => { + console.log(`Room status changed: ${change.previous} → ${change.current}`); + if (change.current === 'released') { + // Handle room release + cleanupRoomReferences(); + } + }); + ``` + ## Automatic Handling -The Chat SDK does not automatically recover from this error. Once a room is released, it cannot be reused. You must explicitly obtain a new room instance. - +The Chat SDK does not automatically recover from this error. Once a room is released, it becomes permanently unusable and cannot be reattached. You must explicitly obtain a new room instance through `rooms.get()`. -## Prevention +The SDK will not: +- Automatically create a new room instance +- Retry operations on released rooms +- Transfer subscriptions to a new room +- Preserve message history from the released room -- **Never cache room instances** beyond their intended lifecycle -- **Always check room status** before performing operations -- **Implement proper cleanup** in your application lifecycle hooks -- **Use room lifecycle events** to track state changes -- **Avoid long-lived references** to room objects - + ## Understanding Room Lifecycle -The Chat SDK implements a room lifecycle state machine: -- **Attached**: Room is connected and operational -- **Detaching**: Room is disconnecting -- **Detached**: Room is disconnected but not released -- **Releasing**: Room is being deallocated -- **Released**: Room is deallocated (triggers error 102103) +The Chat SDK implements a strict room lifecycle state machine to prevent resource leaks and ensure proper cleanup: + +### Room States + +| State | Description | Can Perform Operations | Transition To | +|-------|-------------|------------------------|---------------| +| **Initialized** | Room created but not yet attached | Limited | Attached, Released | +| **Attached** | Room is connected and fully operational | Yes | Detaching, Releasing | +| **Detaching** | Room is disconnecting from Ably | No | Detached, Failed | +| **Detached** | Room disconnected but resources retained | Limited | Attached, Releasing | +| **Releasing** | Room is being deallocated (error 102102) | No | Released | +| **Released** | Room fully deallocated (error 102103) | No | Terminal state | +| **Failed** | Unrecoverable error occurred (error 102101) | No | Releasing | + +### Key Points + +- **Released is terminal**: Once a room reaches the Released state, it cannot be reused +- **Resource cleanup**: The Released state ensures all resources are properly deallocated +- **Memory safety**: This design prevents use-after-free type bugs +- **Explicit lifecycle**: Developers must explicitly manage room instances + + + +## Code Examples + +### Proper Room Management Pattern + +```javascript +// JavaScript/TypeScript - Room manager class +class ChatRoomManager { + constructor(chat) { + this.chat = chat; + this.rooms = new Map(); + } + + async getRoom(roomId) { + // Check if we have a valid room + const existing = this.rooms.get(roomId); + if (existing && existing.status !== 'released') { + return existing; + } + + // Create new room instance + const room = await this.chat.rooms.get(roomId); + await room.attach(); + + // Monitor lifecycle + room.on('status', (change) => { + if (change.current === 'released') { + this.rooms.delete(roomId); + } + }); + + this.rooms.set(roomId, room); + return room; + } + + async releaseRoom(roomId) { + const room = this.rooms.get(roomId); + if (room && room.status !== 'released') { + await room.release(); + this.rooms.delete(roomId); + } + } + + async releaseAll() { + const promises = Array.from(this.rooms.keys()).map(roomId => + this.releaseRoom(roomId) + ); + await Promise.all(promises); + } +} +``` + + +## Prevention + +- **Implement proper cleanup**: Always release rooms in component cleanup/unmount handlers +- **Use lifecycle events**: Monitor room state changes to handle transitions gracefully +- **Avoid long-lived references**: Don't cache room instances in global state +- **Handle errors gracefully**: Implement try-catch blocks around room operations +- **Synchronize async operations**: Ensure async operations check room state before execution +- **Use weak references**: Consider WeakMap for room caches to allow garbage collection +- **Implement retry logic**: Handle 102103 errors by obtaining new room instances + -Once a room reaches the Released state, it cannot be reused. This is a terminal state designed to prevent use-after-free type bugs. - +## Related Errors + +• **[102100 - Room Discontinuity](https://help.ably.io/error/102100)** + Room state lost due to connection issues, requiring re-synchronization of room state and presence + +• **[102101 - Room in Failed State](https://help.ably.io/error/102101)** + Room encountered an unrecoverable error and cannot continue operation, requires new room instance + +• **[102102 - Room is Releasing](https://help.ably.io/error/102102)** + Operation attempted while room release is in progress, wait for release to complete + +• **[102106 - Room Released Before Operation Completed](https://help.ably.io/error/102106)** + Race condition where room was released during an ongoing asynchronous operation + +• **[102107 - Invalid Room State](https://help.ably.io/error/102107)** + Room state machine violation detected, indicates potential SDK bug or improper state manipulation ## Related Resources - [Ably Chat documentation](https://ably.com/docs/chat) - [Chat SDK room lifecycle](https://ably.com/docs/chat/rooms) -- Related errors: - - [102100](./102100-room-discontinuity.mdx) - Room discontinuity - - [102101](./102101-room-in-failed-state.mdx) - Room in failed state - - [102102](./102102-room-is-releasing.mdx) - Room is releasing +- [Chat SDK best practices](https://ably.com/docs/chat/best-practice) +- [Chat SDK API reference](https://ably.com/docs/api/chat) ## Need Further Help? @@ -158,43 +336,54 @@ Our team will help you resolve this issue as quickly as possible. - + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/102106-room-released-before-operation-completed.mdx b/src/pages/docs/platform/errors/codes/102106-room-released-before-operation-completed.mdx index 994c14657b..5bdd2ca82a 100644 --- a/src/pages/docs/platform/errors/codes/102106-room-released-before-operation-completed.mdx +++ b/src/pages/docs/platform/errors/codes/102106-room-released-before-operation-completed.mdx @@ -1,13 +1,13 @@ - + - + # Error 102106: Room released before operation completed @@ -39,17 +39,19 @@ You'll see this message: - Component unmounting while room initialization is in progress - User navigation triggering cleanup during room loading - Multiple components managing the same room simultaneously - + 2. **Application shutdown during initialization** (20% of cases) - App cleanup running while rooms are being fetched - Browser/app closing during async operations - + - Background task cancellation in mobile apps + 3. **Improper async operation handling** (10% of cases) - Not awaiting room operations before cleanup - Missing coordination between room get and release calls - + - Parallel operations without proper synchronization + ## Resolution Steps @@ -72,25 +74,31 @@ You'll see this message: } } ``` - + 2. **Improve your room lifecycle management** - Implement a centralized room manager to coordinate access - Use reference counting for shared room instances - Ensure cleanup operations wait for initialization to complete - + - Track pending operations and cancel them appropriately + 3. **Fix component lifecycle issues (React example)** ```javascript useEffect(() => { let cancelled = false; + let room = null; async function setupRoom() { try { - const room = await chat.rooms.get('my-room-id'); + const newRoom = await chat.rooms.get('my-room-id'); if (!cancelled) { // Only use room if component is still mounted - setRoom(room); + room = newRoom; + setRoom(newRoom); + } else { + // Component unmounted during get - release immediately + await chat.rooms.release('my-room-id'); } } catch (error) { if (error.code === 102106 && !cancelled) { @@ -111,23 +119,31 @@ You'll see this message: }; }, []); ``` - + 4. **Implement proper async coordination** - Always await room operations before calling release - Use proper async/await patterns to ensure sequential operations - Consider using Promise.allSettled() for multiple room operations - + - Track operation states to prevent premature cleanup + + +5. **Use platform-specific patterns** + - **JavaScript**: Leverage AbortController for clean cancellation + - **Kotlin/Android**: Use coroutines with proper exception handling + - **Swift/iOS**: Implement actor-based state management + ## Automatic Handling The Chat SDKs automatically: - Cancel pending `rooms.get()` operations when `rooms.release()` is called - Clean up resources to prevent memory leaks -- Log debug information about the cancellation +- Log debug information about the cancellation (varies by SDK) +- Comply with the CHA-RC1g4 specification requirement -This error is part of the defensive programming built into the SDK to ensure proper resource cleanup. - +This error is part of the defensive programming built into the SDK to ensure proper resource cleanup and prevent race conditions. + ## Prevention @@ -135,14 +151,23 @@ This error is part of the defensive programming built into the SDK to ensure pro - **Use proper lifecycle management**: Implement cleanup in the correct component lifecycle phase - **Handle async operations properly**: Always await or properly handle promises - **Implement room reference counting**: Track active users of a room before releasing - +- **Use cancellation tokens**: Implement proper cancellation mechanisms for long-running operations +- **Centralize room management**: Create a singleton room manager to coordinate access across components + ## Related Resources -- [Ably Chat documentation](https://ably.com/docs/chat) +- [Ably Chat documentation](https://ably.com/docs/products/chat) - [Chat Rooms API reference](https://ably.com/docs/chat/rooms) - [Chat SDK Specification CHA-RC1g4](https://github.com/ably/specification/tree/main/textile/chat#CHA-RC1g4) -- Related errors: None currently - this is a Chat-specific error + +## Related Errors + +Since this is a Chat SDK-specific error related to room lifecycle management, there are currently no directly related error codes. However, you may encounter other Chat SDK errors in similar scenarios: + +• **General Chat SDK errors** - Other errors in the 102xxx range relate to Chat SDK functionality +• **Connection errors** - If the underlying connection fails, you may see 80xxx errors +• **Authentication errors** - Room access may fail with 401xx errors if authentication is invalid ## Need Further Help? @@ -163,46 +188,51 @@ Our team will help you resolve this issue as quickly as possible. - + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/102107-room-invalid-state.mdx b/src/pages/docs/platform/errors/codes/102107-room-invalid-state.mdx index ca40769a5c..6dd9ee05e6 100644 --- a/src/pages/docs/platform/errors/codes/102107-room-invalid-state.mdx +++ b/src/pages/docs/platform/errors/codes/102107-room-invalid-state.mdx @@ -1,32 +1,32 @@ - + - + # Error 102107: Room invalid state ## What Happened -The Chat SDK cannot perform the requested operation because the chat room is not in the correct state. +The Chat SDK cannot perform the requested operation because the chat room is not in the correct state for that operation. ## Quick Reference | Error Code | HTTP Status | Category | Retryable | |------------|-------------|----------|-----------| -| 102107 | 400/500 | Client Error (Chat SDK) | No - requires room attachment | +| 102107 | 400/500 | Client Error (Chat SDK) | No - requires fixing room state | ## Quick Fix -- Attach the room before performing presence operations -- Wait for room to reach ATTACHED state -- Check room status before operations +- Ensure the room is attached before performing presence operations +- Wait for room to reach ATTACHED state before operations +- Check room.status before attempting any presence operations ## Error Messages @@ -35,36 +35,39 @@ You may see one of these messages: - "The room operation failed because the room was in an invalid state." - "To perform this {feature} operation, you must first attach the room." -The `{roomName}` shows the specific room identifier, `{roomStatus}` shows the current room state, and `{feature}` indicates the operation type (e.g., presence). +The `{roomName}` shows the specific room identifier, `{roomStatus}` shows the current room state (e.g., INITIALIZED, SUSPENDED, FAILED), and `{feature}` indicates the operation type (typically "presence"). ## Common Causes 1. **Room not attached** (80% of cases) - - - Attempting presence operations before attaching room - - Room in INITIALIZED, SUSPENDED, or FAILED state - - Missing room.attach() call + + - Attempting presence operations before calling room.attach() + - Room is in INITIALIZED state (never attached) + - Forgot to attach room after getting it from rooms collection 2. **Room state transition failure** (15% of cases) - + - Room was ATTACHING but transitioned to non-ATTACHED state - - Network interruption during attachment - - Authentication issues during attachment + - Network interruption during attachment process + - Authentication failure during room attachment 3. **Room in terminal state** (5% of cases) - - - Room is FAILED or SUSPENDED - - Previous error left room in unusable state - - Room requires reinitialization + + - Room is in FAILED state from previous error + - Room is SUSPENDED after prolonged disconnection + - Room requires reinitialization to recover ## Resolution Steps -1. **Attach the room before operations** - +1. **Attach the room before any operations** + ```kotlin // Kotlin/Android val room = chatClient.rooms.get(roomId) + + // Attach room first room.attach() + // Now safe to perform presence operations room.presence.enter() ``` @@ -72,13 +75,16 @@ The `{roomName}` shows the specific room identifier, `{roomStatus}` shows the cu ```swift // Swift/iOS let room = chatClient.rooms.get(roomID: roomId) + + // Attach room first try await room.attach() + // Now safe to perform presence operations try await room.presence.enter() ``` 2. **Check room status before operations** - + ```kotlin // Kotlin/Android if (room.status == RoomStatus.ATTACHED) { @@ -87,11 +93,26 @@ The `{roomName}` shows the specific room identifier, `{roomStatus}` shows the cu } else { // Attach first room.attach() + // Then perform operation + room.presence.update(userData) + } + ``` + + ```swift + // Swift/iOS + if room.status == .attached { + // Safe to perform operations + try await room.presence.update(userData) + } else { + // Attach first + try await room.attach() + // Then perform operation + try await room.presence.update(userData) } ``` -3. **Handle state transition failures** - +3. **Handle state transition failures gracefully** + ```swift // Swift/iOS do { @@ -99,34 +120,110 @@ The `{roomName}` shows the specific room identifier, `{roomStatus}` shows the cu } catch { if let ablyError = error as? ARTErrorInfo, ablyError.code == 102107 { - // Attach room and retry + // Room not attached - attach and retry try await room.attach() try await room.presence.enter() } } ``` + + ```kotlin + // Kotlin/Android + try { + room.presence.enter() + } catch (e: AblyException) { + if (e.errorInfo.code == 102107) { + // Room not attached - attach and retry + room.attach() + room.presence.enter() + } + } + ``` 4. **Monitor room status changes** - - Subscribe to room status changes to ensure operations only occur when room is attached. This prevents the error from occurring in the first place. + + Subscribe to room status changes to track state transitions and ensure operations only occur when the room is properly attached. This proactive approach prevents the error from occurring. ## Automatic Handling -The Chat SDK does not automatically retry this error. You must explicitly attach the room and retry the operation. +The Chat SDK does not automatically retry this error. Room attachment is an explicit operation that must be initiated by your application. Once attached, the room will maintain its state unless explicitly detached or a terminal error occurs. + +## Code Examples + +### Complete Room Initialization Pattern + +```kotlin +// Kotlin/Android - Proper room initialization +class ChatRoomManager { + suspend fun joinRoom(roomId: String, userData: Map) { + val room = chatClient.rooms.get(roomId) + + // Always attach before operations + room.attach() + + // Now safe to enter presence + room.presence.enter(userData) + + // Subscribe to messages + room.messages.subscribe { message -> + handleMessage(message) + } + } +} +``` + +```swift +// Swift/iOS - Proper room initialization +class ChatRoomManager { + func joinRoom(roomID: String, userData: [String: Any]) async throws { + let room = chatClient.rooms.get(roomID: roomID) + + // Always attach before operations + try await room.attach() + + // Now safe to enter presence + try await room.presence.enter(userData: userData) + + // Subscribe to messages + room.messages.subscribe { message in + self.handleMessage(message) + } + } +} +``` ## Prevention -- Always call `room.attach()` before any presence operations -- Implement room status listeners to track state changes -- Use try-catch blocks around presence operations -- Wait for room attachment to complete before proceeding +- **Always attach rooms explicitly**: Call `room.attach()` immediately after getting a room reference +- **Implement status monitoring**: Subscribe to room status changes to track state transitions +- **Use try-catch blocks**: Wrap all presence operations in proper error handling +- **Check room state**: Verify room.status == ATTACHED before presence operations +- **Handle reconnection**: Re-attach rooms after connection recovery if needed + +## Performance Impact + +This error indicates a logic issue rather than a performance problem. However, repeatedly encountering this error suggests inefficient room lifecycle management that could impact: +- User experience with failed presence updates +- Increased latency from retry attempts +- Unnecessary network requests from improper sequencing ## Related Resources -- [Ably Chat documentation](https://ably.com/docs/chat) -- [Chat SDK room lifecycle](https://ably.com/docs/chat/rooms) -- [Presence in Chat](https://ably.com/docs/chat/rooms#presence) -- Related errors: [80000](./80000-connection-failed.md), [91001](./91001-channel-operation-failed.md) +- [Ably Chat Rooms documentation](https://ably.com/docs/chat/rooms) +- [Chat Presence documentation](https://ably.com/docs/chat/rooms/presence) +- [Chat SDK Getting Started - Kotlin](https://ably.com/docs/chat/getting-started/kotlin) +- [Chat SDK Getting Started - JavaScript](https://ably.com/docs/chat/getting-started/javascript) + +## Related Errors + +• **[80000 - Connection Failed](https://help.ably.io/error/80000)** + Underlying connection failure that can prevent room attachment + +• **[90000 - Channel Operation Failed](https://help.ably.io/error/90000)** + General channel operation failure that may affect room state + +• **[91001 - Unable to Enter Presence](https://help.ably.io/error/91001)** + Related presence operation failure when client ID is not configured ## Need Further Help? @@ -148,41 +245,47 @@ Our team will help you resolve this issue as quickly as possible. + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/20000-informational-status.mdx b/src/pages/docs/platform/errors/codes/20000-informational-status.mdx index d4ba325c48..cc91908285 100644 --- a/src/pages/docs/platform/errors/codes/20000-informational-status.mdx +++ b/src/pages/docs/platform/errors/codes/20000-informational-status.mdx @@ -1,11 +1,11 @@ - + @@ -48,31 +48,31 @@ This isn't an error but appears in these normal scenarios: - WebSocket connection replacing an older connection - Multiple browser tabs or iframes connecting to same channel - Transport protocol switching (WebSocket to HTTP or vice versa) - + 2. **Resource cleanup** (20% of occurrences) - Unused connections being closed - Idle coordinators shutting down - Global resources being disposed - + 3. **Channel management** (20% of occurrences) - Channel relocations on backend - Inactive channels declining lifecycle tokens - Channel attachment state changes - + ## Why You're Seeing This Error 20000 appears in logs during normal Ably operations. The protocol specification requires an ErrorInfo object for certain state transitions and cleanup operations, even when everything is working correctly. Think of it as an "FYI" status rather than an error. - + Common situations where you'll see this: - Opening your app in multiple browser tabs - Recovering from temporary network disconnections - Normal connection lifecycle during long-running sessions - Backend load balancing operations - + ## Resolution Steps @@ -87,7 +87,7 @@ Since this isn't an actual error, no resolution is needed. However, if you're co - "Transport superseded" means a newer connection replaced an older one (normal) - "Resource being disposed" means cleanup of unused resources (normal) - "Coordinator idle" means the coordinator entered standby mode (normal) - + 3. **Monitor for actual issues** - Look for error codes in the 40xxx, 50xxx, or 80xxx ranges @@ -101,7 +101,7 @@ Ably SDKs handle all scenarios that generate error 20000 automatically. The SDK: - Cleans up resources as needed - Handles channel relocations seamlessly - Maintains message delivery throughout these operations - + ## Prevention @@ -114,9 +114,20 @@ You cannot and should not try to prevent error 20000—it's a normal part of Abl ## Related Resources - [Connection state management](https://ably.com/docs/realtime/connection) -- [Understanding Ably's protocol](https://ably.com/docs/client-lib-development-guide/protocol) +- [Understanding Ably's protocol](https://sdk.ably.com/builds/ably/specification/main/protocol) - [Channel lifecycle](https://ably.com/docs/channels) +## Related Errors + +• **[80000 - Connection Failed](https://help.ably.io/error/80000)** + Actual connection failures that require attention, unlike error 20000 + +• **[80014 - Connection Timeout](https://help.ably.io/error/80014)** + Real timeout issues that indicate connection problems + +• **[90000 - Channel Operation Failed](https://help.ably.io/error/90000)** + Channel failures that need resolution, unlike normal channel lifecycle events in 20000 + ## Need Further Help? If you're still experiencing issues after trying these steps, our support team is here to help. @@ -136,15 +147,15 @@ Our team will help you resolve this issue as quickly as possible. - + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/40000-bad-request.mdx b/src/pages/docs/platform/errors/codes/40000-bad-request.mdx index d687c29d6e..fb351ff297 100644 --- a/src/pages/docs/platform/errors/codes/40000-bad-request.mdx +++ b/src/pages/docs/platform/errors/codes/40000-bad-request.mdx @@ -1,13 +1,13 @@ - + - + # Error 40000: Bad request @@ -25,15 +25,17 @@ Your request cannot be processed because it doesn't meet Ably's requirements. Th ## Quick Fix - Check the specific error message for details about what's wrong -- Verify all parameters are the correct type and format +- Verify all parameters are the correct type and format - Ensure the connection and channel are in the correct state for your operation - Review feature enablement if using Chat SDK features +- For .NET SDK: Check serialization settings if seeing decode failures ## Error Messages You may see one of these messages: - + + - "Unable to publish in Suspended state" - Connection suspended after 2+ minutes disconnected - "Message cannot be published. Client is not allowed to queue messages when connection is in Initialized state" - Message queueing is disabled - "Channel is not attached" - Channel must be attached before operations @@ -46,77 +48,89 @@ You may see one of these messages: - "cannot subscribe to occupancy; occupancy events are not enabled in room options" - Feature not enabled - "invalid Timeserial {value}, missing @ character" - Malformed timeserial format - "invalid Timeserial {value}, missing - character" - Malformed timeserial format +- "Context must be an array of objects with role and content keys" - Control API format error +- "unable to run LiveObjects QoS test API key or realtime Endpoint not set" - Missing configuration +- "{hook} hook must be used within a " - React context error (Chat SDK) +- "Channel has been attached, but channelSerial is not defined" - Missing channel serial +- "cannot query history; listener has not been subscribed yet" - Subscription order violation - + ## Common Causes -### 1. Parameter Validation Errors (40% of cases) -- **Wrong data types**: Providing string when object expected, or vice versa -- **Format violations**: Invalid timeserials, channel names, or client IDs -- **Missing required fields**: Required parameters not provided -- **Values out of range**: Message size exceeded, recipient count over limit - - - -### 2. State Prerequisites Not Met (35% of cases) +### 1. State Prerequisites Not Met (35% of cases) - **Publishing in suspended state**: Connection has been disconnected for over 2 minutes - **Channel not attached**: Attempting operations before channel attachment - **Connection not established**: Operations attempted before connection is ready - **Message queueing disabled**: `queueMessages: false` prevents automatic queueing - **Component lifecycle violations**: Operations on unmounted or disposed components - - + + + +### 2. Parameter Validation Errors (30% of cases) +- **Wrong data types**: Providing string when object expected, or vice versa +- **Format violations**: Invalid timeserials, channel names, or client IDs +- **Missing required fields**: Required parameters not provided +- **Values out of range**: Message size exceeded, recipient count over limit +- **Control API context format**: String provided instead of array of objects + + + ### 3. Feature Not Enabled (15% of cases) - **Presence operations**: Attempting presence without enabling in room options - **Occupancy tracking**: Using occupancy features without enabling them - **Typing indicators**: Starting typing without enabling the feature - **Reactions**: Using reactions without enabling in room configuration +- **LiveObjects**: Missing API key or endpoint configuration - + + -### 4. Protocol and Serialization Issues (5% of cases) +### 4. Protocol and Serialization Issues (10% of cases) - **.NET SDK serialization**: Custom serializers sending enums as strings instead of integers - **WebSocket message format**: Protocol messages improperly formatted - **Batch format errors**: JSON sent instead of msgpack for batch operations - **Timeserial parsing**: Missing separators or non-numeric components +- **Transport decode failures**: Invalid websocket message format - + + -### 5. Resource Conflicts (5% of cases) +### 5. Resource Conflicts (10% of cases) - **Duplicate resources**: Attempting to create already existing resources - **Configuration conflicts**: Getting room with different options than originally specified - **Immutable modifications**: Trying to change channel options after creation - **Transport superseded**: Newer connection has replaced the current transport - + ## Resolution Steps ### 1. For State-Related Errors **If you see "Unable to publish in Suspended state":** - + 1. The connection has been disconnected for over 2 minutes and entered suspended state 2. Create a new connection or wait for automatic recovery 3. Monitor connection state to prevent future suspensions -4. See [Connection state management documentation](https://ably.com/docs/realtime/connection#connection-state-recovery) +4. See [Connection state and recovery documentation](https://ably.com/docs/connect/states) **If you see "Message cannot be published" with connection state errors:** - + 1. Check if `queueMessages` is set to `false` in your client options 2. If so, either: - Enable message queueing (recommended): Set `queueMessages: true` in client options - Or wait for connection before publishing (only if queueing must be disabled) 3. With default settings, messages are automatically queued - this error indicates a configuration issue +4. See [Message queueing documentation](https://ably.com/docs/connect/states#queueing) **For "Channel is not attached" errors:** 1. With default settings, messages are automatically queued - this error indicates a configuration issue 2. If you've disabled queueing (`queueMessages: false`), wait for attachment before operations 3. Review [Channel lifecycle documentation](https://ably.com/docs/channels) - + ### 2. For Parameter Validation Errors @@ -124,25 +138,28 @@ You may see one of these messages: 2. **Verify parameter types** match the API requirements: - `options.params` must be an object, not a string - `options.modes` must be an array - - Context parameters must be arrays of objects -3. **Validate channel names** against [naming requirements](https://ably.com/docs/channels#name-syntax) + - Context parameters must be arrays of objects with role and content keys +3. **Validate channel names** against [naming requirements](https://ably.com/docs/channels#channel-namespaces) 4. **Check SDK documentation** for specific parameter formats - + + ### 3. For .NET SDK Serialization Errors If you see "Unable to read from transport: msg=invalid websocket message (decode failure)": - + + 1. **Check your custom serializers** - ensure enums serialize as integers, not strings 2. **Verify protocol message format** - action fields must be integers 3. **Review serialization configuration** for default settings 4. Ensure your JSON serializer doesn't convert numeric enums to strings +5. Check the raw WebSocket message format - action field should be numeric (e.g., action:9 not action:"9") ### 4. For Push Notification Recipient Limits If you see "Total recipients exceeds maximum allowed 1000": - + 1. **Batch your recipients** in groups of 1000 or fewer 2. **Implement batching logic** in your application @@ -156,8 +173,9 @@ If you see "Total recipients exceeds maximum allowed 1000": - Enable typing for typing indicators - Enable occupancy for occupancy tracking - Enable reactions for reaction features -3. See [Chat room configuration documentation](https://ably.com/docs/chat/rooms) - +3. **For React hooks**: Ensure they're used within the proper provider context +4. See [Chat room configuration documentation](https://ably.com/docs/chat/rooms) + ### 6. For Timeserial Format Errors @@ -166,7 +184,16 @@ If you see errors about invalid timeserials: 2. **Structure**: `@-` 3. **Components**: All parts must be valid integers 4. See [Message ordering documentation](https://ably.com/docs/metadata-stats/metadata/subscribe#serial) - + + +### 7. For LiveObjects Configuration Errors + +If you see "unable to run LiveObjects QoS test API key or realtime Endpoint not set": + +1. **Verify API key** is correctly configured +2. **Check endpoint configuration** for LiveObjects +3. **Ensure environment variables** are properly set +4. See [LiveObjects documentation](https://ably.com/docs/products/liveobjects) ## Automatic Handling @@ -177,7 +204,7 @@ Ably SDKs do not automatically retry 40000 errors as they indicate issues with y With default settings (`queueMessages: true`), messages are automatically queued during temporary disconnections, so you should rarely see state-related 40000 errors in normal operation. - + ## Prevention @@ -188,8 +215,10 @@ With default settings (`queueMessages: true`), messages are automatically queued - **Implement proper error handling** to catch and respond to validation failures - **Use current SDK versions** to benefit from improved error handling - **Test serialization** if using custom serializers in .NET SDK +- **Batch bulk operations** to respect system limits - + + ## Performance Impact @@ -205,24 +234,28 @@ This error prevents the specific operation but doesn't affect: Connection-level failures that may lead to suspended state and 40000 errors • **[80002 - Connection Suspended](https://help.ably.io/error/80002)** - The suspended state that triggers "Unable to publish" 40000 errors + The suspended state that triggers "Unable to publish" 40000 errors after 2+ minutes disconnected • **[80003 - Connection Disconnected](https://help.ably.io/error/80003)** - Temporary disconnection that may cause 40000 if queueing is disabled + Temporary disconnection that may cause 40000 if queueing is disabled with `queueMessages: false` • **[90000 - Channel Operation Failed](https://help.ably.io/error/90000)** Channel-specific failures that may manifest as 40000 in some cases • **[40101 - Invalid API Key](https://help.ably.io/error/40101)** - Authentication errors that are more specific than general 40000 + Authentication errors that are more specific than general bad request + +• **[40400 - Not Found](https://help.ably.io/error/40400)** + Resource not found errors that are more specific than general bad request ## Related Resources -- [Connection state management](https://ably.com/docs/realtime/connection) +- [Connection state and recovery](https://ably.com/docs/connect/states) - [Channel parameters documentation](https://ably.com/docs/channels/options) - [Push notification limits](https://ably.com/docs/push/publish) - [Chat room configuration](https://ably.com/docs/chat/rooms) -- [Message queueing behavior](https://ably.com/docs/realtime/connection#queue-messages) +- [Message queueing behavior](https://ably.com/docs/connect/states#queueing) +- [Channel naming requirements](https://ably.com/docs/channels#channel-namespaces) ## Need Further Help? @@ -244,45 +277,53 @@ Our team will help you resolve this issue as quickly as possible. - - + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/40001-invalid-request-body.mdx b/src/pages/docs/platform/errors/codes/40001-invalid-request-body.mdx index 7dbf9b184f..67116ff68d 100644 --- a/src/pages/docs/platform/errors/codes/40001-invalid-request-body.mdx +++ b/src/pages/docs/platform/errors/codes/40001-invalid-request-body.mdx @@ -1,11 +1,11 @@ - + @@ -24,9 +24,12 @@ The request sent to Ably contains invalid, malformed, or incomplete data that ca ## Quick Fix -- Verify your request body is valid JSON or MessagePack format -- Ensure all required fields are present and not empty +- Verify your request body is valid JSON format (MessagePack has limitations) +- Ensure all required fields are present and not empty - Check that your Content-Type header matches your request format +- For Chat operations, confirm the `text` field is not empty +- For token requests, include both `keyName` and `nonce` parameters +- For batch operations, check the `batchResponse` field for individual errors ## Error Messages @@ -40,6 +43,7 @@ You may encounter one of these specific error messages: - "unable to add message reaction; type is invalid" - "unable to add message reaction; name is empty" - "unable to delete message reaction; type is empty" +- "cannot delete reaction of type [type] without a name" - "invalid JSON data" - "invalid MessagePack data" - "invalid utf-8 data" @@ -47,8 +51,14 @@ You may encounter one of these specific error messages: - "invalid response content-type" - "invalid room configuration: [reason]" - "Typing heartbeatThrottle must be greater than 0" -- "cannot delete reaction of type [type] without a name" - "Raw message reactions are not enabled" +- "unable to handle plain data; incompatible request" +- "unable to handle form encoded data; incompatible request" +- "unable to handle binary data; incompatible request" +- "unable to update chat message; text is empty" +- "unable to delete chat message; cannot decode request body" +- "unable to send reaction; name not set and it is required" +- "unable to add message reaction; count provided for type that doesn't support a count" ## Common Causes @@ -57,27 +67,30 @@ You may encounter one of these specific error messages: - Improperly encoded MessagePack data - Invalid UTF-8 encoding in text fields - MessagePack used where only JSON is supported (e.g., LiveObjects API) - + + 2. **Missing required fields** (35% of cases) - - Empty `text` field in chat messages + - Empty `text` field in chat messages or updates - Missing `keyName` in token requests - Missing `nonce` in non-key-authenticated token requests - Missing `type` or `name` in reactions - + 3. **Missing or incorrect Content-Type header** (15% of cases) - No Content-Type header in request - Content-Type doesn't match actual request format - - Using unsupported content types (plain text, form-encoded, octet-stream) - + - Using unsupported content types (plain text, form-encoded, octet-stream for Chat APIs) + 4. **Invalid configuration values** (10% of cases) - Non-positive typing throttle values (must be > 0) - Invalid reaction types - Incompatible room configuration options - Raw reactions used without enabling in room options - + - Count field provided for non-Multiple reaction types + + ## Resolution Steps @@ -86,51 +99,65 @@ You may encounter one of these specific error messages: - Check for common syntax errors like missing quotes, commas, or brackets - If using MessagePack, verify your encoding is correct - Note: LiveObjects API currently only supports JSON, not MessagePack - - + - For batch publish operations, ensure proper MessagePack encoding if used + + + 2. **Review required fields for your operation** For **chat messages**: - - Ensure the `text` field is present and not empty + - Ensure the `text` field is present and not empty (required for both send and update) - Include all required metadata fields - + - For room reactions, include the `name` field + - When deleting messages with reactions, remove reactions first to avoid decode errors + + + For **token requests**: - Include the `keyName` parameter - Add a unique `nonce` value for non-key-authenticated requests - Ensure timestamp is formatted as string or number - - + + For **reactions**: - - Provide `type` field (required for all reactions) + - Provide `type` field (required for all reactions, valid types: "Unique", "Multiple", and custom types) - Include `name` field for non-unique reaction types - - Only use `count` field with "Multiple" type reactions + - Only use `count` field with "Multiple" type reactions (other types will error if count is provided) - Enable raw reactions in room options before using - - + - When deleting reactions, provide both `type` and `name` for non-unique reactions + + + 3. **Set proper HTTP headers** - Include `Content-Type: application/json` for JSON requests - Use `Content-Type: application/x-msgpack` for MessagePack (where supported) - Ensure character encoding is UTF-8 - + - Note: Chat APIs reject plain text and form-encoded content types + - Token endpoints support both JSON and form-encoded formats + + 4. **Check SDK-specific requirements** - Review the API documentation for your specific SDK - Verify you're using the correct method signatures - Ensure proper serialization settings in your language - Keep your SDK updated to the latest version - + - For Java SDK, use `newBatchResponse` parameter to access detailed batch errors + + 5. **Debug with minimal payload** - Start with the simplest valid request - Gradually add optional parameters - Log the exact request body being sent - - Check for batch operation error masking (40020 may hide 40001 errors) - - + - For batch operations, check the `batchResponse` field for individual 40001 errors (may be masked by 40020) + - Check individual error targets in batch responses for specific failures + + ## Automatic Handling @@ -143,30 +170,37 @@ This is a client error that will not be automatically retried by Ably SDKs. You - Implement request validation in your application layer - Test with various payload sizes and character sets - Be aware of API-specific limitations (e.g., LiveObjects is JSON-only) -- For batch operations, check the batchResponse field for individual errors - - +- For batch operations, always check the `batchResponse` field for individual errors +- When deleting chat messages with reactions, remove reactions first to avoid decode errors +- For room configuration, ensure all numeric values are positive (e.g., `heartbeatThrottle` > 0) +- Remember that only "Multiple" type reactions support a count field +- Test MessagePack encoding thoroughly, especially for batch publish operations + + + + ## Related Resources -- [Ably REST API Documentation](https://ably.com/docs/api/rest-api) -- [Ably Chat SDK Documentation](https://ably.com/docs/chat/setup) -- [Token Authentication Documentation](https://ably.com/docs/auth/token) -- [REST API Token Request Specification](https://ably.com/docs/api/token-request-spec) +- [Ably Documentation](https://ably.com/docs) +- [Authentication Documentation](https://ably.com/docs/auth) +- [Chat Documentation](https://ably.com/docs/products/chat) +- [API Reference](https://ably.com/docs/api) +- [Error Codes Reference](https://help.ably.io/error/40001) ## Related Errors -• **[40003 - Invalid Parameter Value](https://faqs.ably.com/error-40003)** - More specific validation errors for individual parameter values +• **[40003 - Invalid Parameter Value](https://help.ably.io/error/40003)** + More specific validation errors for individual parameter values beyond request body structure • **[40012 - Invalid Client ID](https://help.ably.io/error/40012)** - Client ID validation errors in messages and presence operations + Client ID validation errors that may occur alongside request body issues • **[40013 - Invalid Message Data](https://help.ably.io/error/40013)** - Message data encoding and format validation errors + Message data encoding and format validation errors for message content specifically • **[40020 - Batch Response Contains Errors](https://help.ably.io/error/40020)** - May mask individual 40001 errors in batch operations - check batchResponse field + May mask individual 40001 errors in batch operations - always check batchResponse field for details ## Need Further Help? @@ -188,31 +222,39 @@ Our team will help you resolve this issue as quickly as possible. - - + + + @@ -243,6 +285,21 @@ Our team will help you resolve this issue as quickly as possible. - Impact: Developers may attempt MessagePack with unsupported endpoints, receiving confusing errors - Recommendation: Document encoding support matrix for all APIs clearly - Severity: Medium - causes confusion but workaround exists (use JSON) + +- Missing: Clear documentation about chat message deletion with reactions limitation +- Impact: Developers encounter unexpected decode errors when deleting messages with reactions +- Recommendation: Document this known limitation and workaround in Chat API docs +- Severity: Medium - workaround exists but not documented + +- Missing: Batch operation error masking pattern documentation +- Impact: Developers may not realize individual 40001 errors are hidden in batchResponse field +- Recommendation: Document batch error response structure clearly +- Severity: Medium - causes debugging confusion + +- Missing: Reaction type validation rules and count field restrictions +- Impact: Developers may not understand which reaction types support count fields +- Recommendation: Document reaction types and their field requirements clearly +- Severity: Low - error messages are descriptive but documentation would prevent errors --> \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/40003-invalid-parameter-value.mdx b/src/pages/docs/platform/errors/codes/40003-invalid-parameter-value.mdx index 81c8bddd1b..20c61d78e7 100644 --- a/src/pages/docs/platform/errors/codes/40003-invalid-parameter-value.mdx +++ b/src/pages/docs/platform/errors/codes/40003-invalid-parameter-value.mdx @@ -1,13 +1,13 @@ - + - + # Error 40003: Invalid Parameter Value @@ -32,8 +32,8 @@ A parameter in your request contains an invalid value that doesn't meet Ably's r You may see one of these messages: - - + + **Token TTL Errors:** - "Excessive value for ttl" - Token TTL exceeds 24-hour maximum @@ -78,50 +78,50 @@ You may see one of these messages: ## Common Causes - - + + 1. **Token TTL exceeding limits** (Most common in production) - Requesting token with TTL > 24 hours for standard tokens - Requesting token with TTL > 1 hour for revocable tokens - Not aware of different limits for revocable vs standard tokens - - + + 2. **Invalid encryption parameters** (Common in PHP implementations) - Missing encryption key when cipher is specified - Unsupported key length (not 128 or 256 bits) - Key length mismatch between declared and actual size - OpenSSL version incompatibility - + 3. **LiveObjects type validation failures** (JavaScript/TypeScript applications) - Non-string keys for LiveMap operations - Non-numeric values for LiveCounter operations - Invalid object structure for setEntries - Type mismatches in batch operations - + 4. **History query parameter errors** - Invalid timestamp formats for start/end parameters - Non-integer or negative limit values - Duplicate parameter specifications - Malformed fromSerial values in chat history - + 5. **Message and annotation validation failures** - Annotations exceeding 4GB size limit - Empty message serials with annotations - Incompatible data types with annotations - Wrong parameter combinations in publish methods - + ## Resolution Steps ### For Token TTL Errors - - + + 1. **Check your token request TTL** ```javascript @@ -141,7 +141,7 @@ You may see one of these messages: // Note: revocation is configured on the API key, not in the request }); ``` - + 2. **Verify your API key configuration** - Check if your API key has revocation enabled in the Ably dashboard @@ -156,8 +156,8 @@ You may see one of these messages: ### For Encryption Errors - - + + 1. **Provide a valid encryption key** ```javascript @@ -175,7 +175,7 @@ You may see one of these messages: } }); ``` - + 2. **Ensure correct key sizes** - Only 128-bit (16 bytes) or 256-bit (32 bytes) keys are supported @@ -192,11 +192,11 @@ You may see one of these messages: $cipher = 'aes-128-cbc'; } ``` - + ### For LiveObjects Errors - + 1. **Use correct data types for map operations** ```javascript @@ -238,8 +238,8 @@ You may see one of these messages: ### For History Query Errors - - + + 1. **Use valid timestamp formats** ```javascript @@ -258,7 +258,7 @@ You may see one of these messages: direction: 'backwards' }); ``` - + 2. **Avoid duplicate parameters** - Ensure start/end parameters appear only once in the query @@ -272,7 +272,7 @@ You may see one of these messages: ### For Message and Annotation Errors - + 1. **Ensure compatible message formats with annotations** ```javascript @@ -329,8 +329,8 @@ This is a client error that will not be automatically retried. You must fix the ## Prevention - - + + - **Validate parameters before API calls**: Check data types and ranges match API requirements - **Use SDK validation methods**: Many SDKs provide built-in validation helpers @@ -353,12 +353,31 @@ Consider implementing client-side validation to catch these errors before making ## Related Resources - [Token Authentication](https://ably.com/docs/auth/token) -- [Encryption Guide](https://ably.com/docs/channels/options/encryption) +- [Encryption Guide](https://ably.com/docs/realtime/encryption) - [LiveObjects Documentation](https://ably.com/docs/products/liveobjects) -- [History API](https://ably.com/docs/storage-history/history) +- [History API](https://ably.com/docs/realtime/history) - [API Limits](https://ably.com/docs/general/limits) -- [Message Formats](https://ably.com/docs/channels/messages) -- Related errors: [40001](./40001-invalid-request-body.mdx), [40004](./40004-invalid-header.mdx), [40005](./40005-invalid-credential.mdx), [40009](./40009-maximum-message-length-exceeded.mdx), [40012](./40012-invalid-client-id.mdx), [40013](./40013-invalid-message-data-or-encoding.mdx) +- [Message Formats](https://ably.com/docs/realtime/messages) + +## Related Errors + +• **[40001 - Invalid Request Body](https://help.ably.io/error/40001)** + Broader request validation errors including malformed JSON or missing required fields + +• **[40004 - Invalid Header](https://help.ably.io/error/40004)** + Header-specific validation failures such as incorrect content-type or encoding + +• **[40005 - Invalid Credential](https://help.ably.io/error/40005)** + Authentication credential validation errors distinct from parameter validation + +• **[40009 - Maximum Message Length Exceeded](https://help.ably.io/error/40009)** + Message size validation failures that may occur alongside parameter errors + +• **[40012 - Invalid Client ID](https://help.ably.io/error/40012)** + Client ID format validation that often accompanies parameter issues + +• **[40013 - Invalid Message Data or Encoding](https://help.ably.io/error/40013)** + Message content validation errors related to encoding and data format ## Need Further Help? @@ -379,23 +398,24 @@ Our team will help you resolve this issue as quickly as possible. - + + + @@ -446,6 +469,6 @@ To improve this error code documentation: 1. First approach: Update editorial-notes.md in ably-os repository with specific guidance for error 40003 2. Regenerate: Run `./bin/ably-os errors document-error-codes 40003 --force` 3. For broader improvements: Review and update ably-os prompt templates -4. Context: See https://github.com/ably/ably-os/blob/main/docs/ERROR_COMMANDS_GUIDE.md +4. Context: See https://github.com/ably/ably-os/blob/5f4ba43/docs/ERROR_COMMANDS_GUIDE.md 5. Source repository: https://github.com/ably/ably-os --> \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/40004-invalid-header.mdx b/src/pages/docs/platform/errors/codes/40004-invalid-header.mdx index c9f0c203d6..4a9fcc2bce 100644 --- a/src/pages/docs/platform/errors/codes/40004-invalid-header.mdx +++ b/src/pages/docs/platform/errors/codes/40004-invalid-header.mdx @@ -1,13 +1,13 @@ - + - + # Error 40004: Invalid header @@ -27,6 +27,7 @@ The server rejected your request due to an invalid or malformed header value tha - Check your HTTP headers for proper formatting and encoding - Verify token TTL is within acceptable limits (≤1 hour) - Ensure all required header attributes are present +- Validate encoding specifications in message headers ## Error Messages @@ -44,26 +45,30 @@ You may see one of these messages: 1. **Invalid HTTP headers** (40% of cases) - Malformed Content-Type headers that can't be parsed - - Link headers missing required attributes + - Link headers missing required attributes (rel or params) - Non-UTF8 encoded header values - + - Headers that don't conform to MIME type standards + 2. **Token TTL exceeds limits** (30% of cases) - JWT tokens with TTL greater than 1 hour - Platform validation incorrectly applied to embedded tokens - - Token expiry calculation issues - + - Token expiry calculation issues (expiryTime - issuedTime) + - JWTs embedding Ably tokens failing validation + 3. **Message encoding issues** (20% of cases) - Invalid or missing encoding format specification - Missing cipher parameters in encrypted messages - - Malformed encoding strings - + - Malformed encoding strings that don't match expected patterns + - Encoding regex validation failures + 4. **Auth callback issues** (10% of cases) - Auth callback responses with invalid Content-Type headers - Token authentication response header parsing failures - + - MIME type parsing errors in authentication flow + ## Resolution Steps @@ -72,40 +77,53 @@ You may see one of these messages: - Ensure Content-Type is a valid MIME type (e.g., "application/json", "text/plain") - For Link headers, include both 'rel' and 'params' attributes - Use proper UTF-8 encoding for all header values - + - Check that headers conform to RFC standards + 2. **For token TTL issues** - Ensure JWT token TTL is 1 hour or less - - Check token expiry time calculation (expiryTime - issuedTime) + - Check token expiry time calculation: `expiryTime - issuedTime` - If using JWTs embedding Ably tokens, verify the surrounding JWT's TTL - - Review [Ably's token authentication documentation](https://ably.com/docs/auth/token) - + - Note: Ably tokens don't store an issued time, which can cause validation issues + - Consider using shorter TTL values to avoid edge cases + 3. **For message encoding issues** - Include format specification in encoding strings - Provide all required cipher parameters for encrypted messages - - Follow the expected encoding string pattern - - See [Ably's message encoding documentation](https://ably.com/docs/realtime/messages#message-encoding) - + - Follow the expected encoding string pattern for your SDK + - Ensure encoding matches the regex validation patterns used by Ably SDKs + 4. **For auth callback issues** - Return valid Content-Type headers from auth callbacks - Ensure headers are parseable MIME types - - Review your auth callback implementation - - Reference [Ably's auth callback documentation](https://ably.com/docs/auth/token#auth-callback) - + - Test your auth callback with tools like curl to verify header format + - Review your auth callback implementation for proper header generation + ## Automatic Handling -This is a client error that will not be automatically retried. You must fix the header format or value before the request will succeed. +This is a client error that will not be automatically retried. You must fix the header format or value before the request will succeed. The error indicates a validation failure that requires correcting the request. ## Prevention - Validate all headers before sending requests -- Use standard HTTP header formatting +- Use standard HTTP header formatting (RFC 7230) - Keep JWT token TTL within 1 hour limit - Test auth callbacks to ensure proper header formatting - Follow Ably's encoding specifications for messages +- Use SDK helper methods for header generation when available +- Implement validation in your code before making API calls + +## Performance Impact + +This error prevents the request from being processed but doesn't affect: +- Existing connections +- Other channels or operations +- The overall connection state + +However, repeated invalid requests may impact your rate limits. ## Related Resources @@ -114,6 +132,17 @@ This is a client error that will not be automatically retried. You must fix the - [Message encoding](https://ably.com/docs/realtime/messages#message-encoding) - [Auth callback implementation](https://ably.com/docs/auth/token#auth-callback) +## Related Errors + +• **[40000 - Bad Request](https://help.ably.io/error/40000)** + General bad request error that may occur for various validation failures + +• **[40101 - Invalid API Key](https://help.ably.io/error/40101)** + Authentication errors that may be related to header issues + +• **[40140 - Token Expired](https://help.ably.io/error/40140)** + Token expiration issues that may occur alongside TTL validation errors + ## Need Further Help? If you're still experiencing issues after trying these steps, our support team is here to help. @@ -133,16 +162,17 @@ Our team will help you resolve this issue as quickly as possible. - + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/40005-invalid-credential.mdx b/src/pages/docs/platform/errors/codes/40005-invalid-credential.mdx index 96f622de7c..a01b676687 100644 --- a/src/pages/docs/platform/errors/codes/40005-invalid-credential.mdx +++ b/src/pages/docs/platform/errors/codes/40005-invalid-credential.mdx @@ -1,20 +1,20 @@ - + - + # Error 40005: Invalid credential ## What Happened -Your authentication credentials (API key or token) are invalid or incorrectly formatted. +Your authentication credentials (API key or token) are invalid or incorrectly formatted, preventing the SDK from authenticating with Ably. ## Quick Reference @@ -24,9 +24,9 @@ Your authentication credentials (API key or token) are invalid or incorrectly fo ## Quick Fix -- Verify your API key format matches: `appId.keyId:keySecret` +- Verify your API key format matches exactly: `appId.keyId:keySecret` - Check that your API key hasn't been revoked in the Ably dashboard -- If using token authentication, ensure the token is correctly generated and not expired +- If using token authentication, ensure the token is correctly formatted as a string (not URL-encoded JSON) ## Error Messages @@ -34,96 +34,132 @@ You may see one of these messages: - "invalid credential" - "API key format is invalid or malformed" - "Invalid accessToken in request: [token details]" +- "Invalid key in request: [partial key]" ## Common Causes 1. **Incorrect API key format** (60% of cases) - - - Missing components in the API key string + + - Missing components in the API key string (app ID, key ID, or secret) - API key not fully copied from dashboard - Using only part of the key instead of the complete string + - Empty or null values for key components 2. **Token authentication issues** (25% of cases) - - - Token incorrectly formatted or URL-encoded + + - Token incorrectly formatted as URL-encoded JSON object - Token generation process has errors - Using an expired token + - Passing a token object instead of token string 3. **Cryptographic validation failures** (10% of cases) - + - HMAC key has invalid length - Signature validation fails + - Incorrect cryptographic parameters 4. **Push notification deregistration** (5% of cases) - + - Occurs during Android push notification cleanup - Often safely ignored per RSH3d2c1 specification + - Deregistration proceeds despite authentication failure ## Resolution Steps ### For API Key Authentication 1. **Verify your API key format** - + - Log into your [Ably dashboard](https://ably.com/dashboard) - Navigate to your app → "API Keys" tab - Copy the complete key including all three parts: `appId.keyId:keySecret` - Ensure you're not missing any characters when copying + - The key should look like: `xVLyHw.rPSJgQ:U6RN3LJvZzV3DXJk` 2. **Check API key permissions** - + - Verify you have admin or owner access to the account - Confirm the key has the necessary capabilities for your operations - Consider creating a new API key with appropriate permissions if needed + - Never use basic authentication client-side as it exposes your API key 3. **Validate in your code** - + - Ensure the API key is passed as a complete string - Check that environment variables are correctly loaded - - Verify no extra spaces or newlines in the key string + - Verify no extra spaces, newlines, or quotes in the key string + - Confirm the key hasn't been truncated or modified ### For Token Authentication 1. **Review token generation** - + - Ensure you're correctly requesting a valid token before using it with Ably - Verify the token request includes all required parameters - Check that the server generating tokens has valid API credentials + - Tokens should be requested from your authentication server, not directly from client-side code 2. **Check token format** - - - Ensure the token isn't being incorrectly URL-encoded - - Verify the token is a string, not a JSON object - - Confirm the token hasn't expired + + - Ensure the token is a string, not a JSON object + - Verify the token isn't being incorrectly URL-encoded + - Common mistake: Passing `%7B%22keyName%22%3A%22...` (URL-encoded JSON) instead of a plain token string + - Confirm the token hasn't expired (tokens are time-limited) 3. **Unity-specific considerations** - + - Known issues exist with token auth in Unity (Issue #1292) - Ensure token is passed as a string, not URL-encoded JSON - - Consider using API key authentication as a temporary workaround + - The token should be the raw token string returned from your auth endpoint + - Consider using API key authentication as a temporary workaround if issues persist ### For Push Notification Context (Android) - -During device deregistration, this error can be safely ignored as the SDK handles it gracefully according to specification RSH3d2c1. The deregistration will proceed despite the authentication failure. + +During device deregistration, this error can be safely ignored as the SDK handles it gracefully according to specification RSH3d2c1. The deregistration will proceed despite the authentication failure. This is expected behavior and doesn't require intervention. + +### SDK-Specific Behaviors + + +- **ably-go**: Pre-validates API key format before attempting connection +- **ably-java**: Special handling in push notification flows (ignores error during deregistration) +- **ably-rust**: Type-safe error conversion from crypto libraries for HMAC validation +- **ably-dotnet**: Known issues with Unity token authentication (see Unity considerations above) ## Automatic Handling -This is a client error that will not be automatically retried. You must provide valid credentials before the operation will succeed. +This is a client error that will not be automatically retried. You must provide valid credentials before the operation will succeed. Authentication failures require manual intervention to correct the credential issue. ## Prevention -- Store API keys securely in environment variables or configuration files +- Store API keys securely in environment variables or secure configuration files +- Never expose API keys in client-side code - use token authentication for client applications - Implement token refresh logic before tokens expire - Validate credential format before initializing the Ably SDK - Use the Ably dashboard to monitor API key usage and permissions +- Set up proper error handling to catch authentication failures early + +## Related Errors + +• **[40101 - Invalid credentials](https://help.ably.io/error/40101)** + Similar authentication error often related to missing application ID in request + +• **[40170 - Invalid API key format](https://help.ably.io/error/40170)** + Specific error for malformed API key structure + +• **[40102 - Token expired](https://help.ably.io/error/40102)** + Related error when using expired token authentication + +• **[40103 - Invalid use of basic auth](https://help.ably.io/error/40103)** + Occurs when using basic auth over non-TLS connections ## Related Resources - [Authentication documentation](https://ably.com/docs/auth) -- [API Keys guide](https://ably.com/docs/auth#api-keys) -- [Token authentication](https://ably.com/docs/auth/token) -- Related errors: [40101 - Invalid credentials](https://help.ably.io/error/40101), [40170 - Invalid API key format](https://help.ably.io/error/40170) +- [Finding your API keys](https://ably.com/docs/ids-and-keys) +- [Token authentication guide](https://ably.com/docs/auth/token) +- [Basic authentication guide](https://ably.com/docs/auth/basic) +- [Setting up and managing API keys](https://faqs.ably.com/setting-up-and-managing-api-keys) ## Need Further Help? @@ -144,43 +180,49 @@ Our team will help you resolve this issue as quickly as possible. - + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/40006-invalid-connection-id.mdx b/src/pages/docs/platform/errors/codes/40006-invalid-connection-id.mdx index b5630dd1dd..29ba0ebb8f 100644 --- a/src/pages/docs/platform/errors/codes/40006-invalid-connection-id.mdx +++ b/src/pages/docs/platform/errors/codes/40006-invalid-connection-id.mdx @@ -1,11 +1,11 @@ - + @@ -39,7 +39,7 @@ You may see one of these messages: ## Common Causes - + 1. **Invalid connectionKey format** (40% of cases) - Using an outdated connectionKey after reconnection @@ -62,7 +62,7 @@ You may see one of these messages: ## Resolution Steps - + 1. **Identify the specific error scenario** - Check the exact error message to determine if it's a connectionKey, connectionId, or lastEvent issue @@ -70,26 +70,26 @@ You may see one of these messages: - Check if connections are identified (have a clientId) 2. **For connectionKey errors (REST publishing on behalf)** - + - Get the current connectionKey from the active realtime connection - Ensure the connectionKey format matches your protocol version - If using identified connections, verify the clientId is included in authentication - Update SDKs to ensure protocol compatibility (protocol v2 in ably-js 1.2.35+) 3. **For connectionId mismatches** - + - Don't set connectionId explicitly in your messages - let the SDK handle it - For presence operations, re-enter presence after connection state changes - Ensure state messages use the current connection's ID 4. **For protocol version issues** - + - Update all SDKs to latest versions for protocol v2 support - Ensure cross-SDK communication uses compatible versions - - Check [SDK compatibility documentation](https://ably.com/docs/sdks) + - Check SDK documentation for compatibility information 5. **For clientId validation issues** - + - Verify your token or API key includes the correct clientId - Ensure the clientId in your authentication matches what you're using - Note: The error message may say "invalid connectionKey" even when the issue is clientId @@ -100,7 +100,7 @@ This is a validation error that will not be automatically retried. You must fix ## Prevention - + - Always use current connectionKeys when publishing on behalf of connections - Let SDKs manage connectionId automatically - don't set it manually @@ -108,13 +108,23 @@ This is a validation error that will not be automatically retried. You must fix - Re-establish presence after connection state changes - Include correct clientId in authentication for identified connections +## Related Errors + +• **[40101 - Invalid API Key](https://help.ably.io/error/40101)** + Authentication errors that may prevent proper connection establishment + +• **[40103 - Invalid Use of Basic Auth](https://help.ably.io/error/40103)** + Authentication issues that can lead to connection validation problems + +• **[80023 - Site Mismatch](https://help.ably.io/error/80023)** + Connection key from different site causing validation failures + ## Related Resources -- [Connection state management](https://ably.com/docs/realtime/connection) -- [Publishing messages](https://ably.com/docs/rest/messages#publish) -- [Identified clients](https://ably.com/docs/auth/identified-clients) -- [Presence documentation](https://ably.com/docs/presence) -- Related errors: [40101](./40101-invalid-api-key.md) (authentication), [40103](./40103-invalid-use-of-basic-auth.md) (auth issues) +- [Connection state management documentation](https://ably.com/docs) +- [Publishing messages documentation](https://ably.com/docs) +- [Identified clients documentation](https://ably.com/docs) +- [Presence documentation](https://ably.com/docs) ## Need Further Help? @@ -135,36 +145,39 @@ Our team will help you resolve this issue as quickly as possible. - + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/40008-invalid-content-length.mdx b/src/pages/docs/platform/errors/codes/40008-invalid-content-length.mdx index fe2143475c..1fe4dda6a4 100644 --- a/src/pages/docs/platform/errors/codes/40008-invalid-content-length.mdx +++ b/src/pages/docs/platform/errors/codes/40008-invalid-content-length.mdx @@ -1,20 +1,20 @@ - + - + # Error 40008: Invalid content length ## What Happened -The request body size doesn't match the Content-Length header value declared in your HTTP request. +The server detected that your HTTP request body contains more data than specified in the Content-Length header, indicating a mismatch between the declared and actual request size. ## Quick Reference @@ -24,69 +24,108 @@ The request body size doesn't match the Content-Length header value declared in ## Quick Fix -- Ensure your HTTP client properly calculates the Content-Length header -- Check that your request body matches the declared content length exactly -- Consider using chunked transfer encoding for streaming data +- Let your HTTP client automatically calculate the Content-Length header +- Verify no proxy or middleware is modifying your request body +- For streaming data, consider using chunked transfer encoding instead ## Error Messages -You may see this message: +You'll encounter this message: - "Invalid content length" ## Common Causes -1. **Mismatched Content-Length header** (most common) - - The Content-Length header value doesn't match the actual request body size - - Data was truncated or expanded during transmission - - Client incorrectly calculated the content length +1. **Content-Length header exceeds actual data** (80% of cases) + + - The declared Content-Length is larger than the data actually sent + - Server receives more data than the Content-Length header indicates + - Typically happens when manually calculating content length incorrectly -2. **HTTP client issues** - - Proxy or middleware modifying the request body - - Network issues causing partial data transmission - - Encoding problems changing the byte size +2. **HTTP client misconfiguration** (15% of cases) + - Manual Content-Length header setting with incorrect byte count + - Character encoding differences affecting byte calculations + - Multi-byte UTF-8 characters counted as single bytes -3. **Manual header setting** - - Manually setting Content-Length without proper byte calculation - - Character encoding differences affecting byte count +3. **Network or proxy interference** (5% of cases) + - Intermediate proxy modifying request body + - Middleware altering content after header is set + - Request body transformation without header update ## Resolution Steps -1. **Let your HTTP client handle Content-Length automatically** - - - Most HTTP clients automatically calculate and set the Content-Length header - - Avoid manually setting this header unless necessary +1. **Allow automatic Content-Length calculation** + + ```javascript + // ✅ Correct: Let the HTTP client handle headers + fetch('https://rest.ably.io/channels/my-channel/messages', { + method: 'POST', + headers: { + 'Authorization': 'Basic ' + apiKey, + 'Content-Type': 'application/json' + // Do NOT manually set Content-Length + }, + body: JSON.stringify(messageData) + }); + + // ❌ Wrong: Manual Content-Length can cause mismatches + fetch('https://rest.ably.io/channels/my-channel/messages', { + method: 'POST', + headers: { + 'Content-Length': '123', // Avoid this + 'Content-Type': 'application/json' + }, + body: JSON.stringify(messageData) + }); + ``` + +2. **If manual Content-Length is required, calculate bytes correctly** + + ```javascript + // Calculate byte length, not character length + const body = JSON.stringify(data); + const byteLength = new TextEncoder().encode(body).length; + // Use byteLength for Content-Length, not body.length + ``` + +3. **Use chunked transfer encoding for dynamic content** + + - Set `Transfer-Encoding: chunked` header + - Omit Content-Length header entirely + - Suitable for streaming or dynamically generated content + +4. **Debug request flow** + - Log Content-Length header value and actual body size + - Check for middleware or proxies that might modify requests + - Use network debugging tools to inspect the raw HTTP request -2. **If manually setting Content-Length, ensure accurate byte counting** - - - Calculate the exact byte length of your request body - - Be aware that character count may differ from byte count with multi-byte characters - - Test with various payload sizes to ensure correct calculation +## Automatic Handling -3. **Consider using chunked transfer encoding for dynamic content** - - - For streaming or dynamically generated content, use Transfer-Encoding: chunked - - This eliminates the need to know content size in advance +This client error is not automatically retried by Ably SDKs. The request validation fails immediately when the server detects more data than declared in the Content-Length header. -4. **Check for intermediate proxies or middleware** - - Verify that no proxy servers are modifying your request - - Ensure any middleware isn't altering the request body after Content-Length is set +## Prevention -## Automatic Handling +- **Use Ably SDKs**: Official SDKs handle all HTTP headers correctly +- **HTTP client libraries**: Use mature libraries that manage headers automatically +- **Avoid manual headers**: Don't set Content-Length unless absolutely necessary +- **Test thoroughly**: Validate with various payload sizes and character encodings +- **Monitor production**: Track this error to identify problematic client implementations -This is a client error that will not be automatically retried. You must fix the Content-Length mismatch before the request will succeed. +## Related Errors -## Prevention +• **[40009 - Max Content Length Exceeded](https://help.ably.io/error/40009)** + Occurs when the request body exceeds Ably's maximum size limits + +• **[40000 - Bad Request](https://help.ably.io/error/40000)** + General request validation errors that may include body format issues -- Use well-established HTTP client libraries that handle headers automatically -- Avoid manually setting Content-Length headers -- For custom implementations, thoroughly test byte counting logic -- Monitor for this error in production to catch edge cases +• **[40003 - Invalid Request Body](https://help.ably.io/error/40003)** + Request body parsing or format validation failures ## Related Resources -- [Ably REST API documentation](https://ably.com/docs/api/rest-api) -- [HTTP request limits](https://ably.com/docs/general/limits#http) -- Related error: 40009 (Max content length exceeded) +- [Ably REST API documentation](https://ably.com/docs/rest) +- [HTTP request limits](https://ably.com/docs/general/limits) +- [Ably SDKs](https://ably.com/download) - Recommended to avoid manual HTTP handling ## Need Further Help? @@ -107,42 +146,46 @@ Our team will help you resolve this issue as quickly as possible. - + + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/40009-message-size-exceeded.mdx b/src/pages/docs/platform/errors/codes/40009-message-size-exceeded.mdx index f6670020a7..3e2446977a 100644 --- a/src/pages/docs/platform/errors/codes/40009-message-size-exceeded.mdx +++ b/src/pages/docs/platform/errors/codes/40009-message-size-exceeded.mdx @@ -1,13 +1,13 @@ - + - + # Error 40009: Message size exceeded @@ -24,85 +24,124 @@ Your message exceeded the maximum size allowed for your Ably package tier. ## Quick Fix -- Check your current package tier's size limit (16KB for Basic, 64KB for Standard) +- Check your current package tier's size limit (64KB for Free/Standard, 256KB for Pro, custom for Enterprise) - Reduce message size by removing unnecessary data or compressing content - Split large messages into smaller chunks if needed -- Consider upgrading your package for higher limits +- For batch publishing, reduce the number of messages per batch +- Consider upgrading to Pro (256KB) or Enterprise for custom limits ## Error Messages You may see one of these messages: - "Maximum message length exceeded" -- "Maximum size of messages that can be published at once exceeded (was X bytes; limit is Y bytes)" - "Maximum message length exceeded (size was X bytes, limit is Y bytes)" +- "Maximum size of messages that can be published at once exceeded (was X bytes; limit is Y bytes)" - "ObjectMessages size X exceeds maximum allowed size of Y bytes" - "Max content length exceeded" - +- "Maximum content length exceeded" + ## Common Causes -1. **Message exceeds package limit** (80% of cases) - - Basic tier: Messages over 16KB (16,384 bytes) - - Standard tier: Messages over 64KB (65,536 bytes) - - Enterprise tier: Messages over custom limit (up to 256KB) - +1. **Message exceeds package limit** (70% of cases) + - Free/Standard tiers: Messages over 64KB (65,536 bytes) + - Pro tier: Messages over 256KB (262,144 bytes) + - Enterprise tier: Messages over custom negotiated limit + - Note: Some older documentation may reference 16KB limits, but current tiers offer higher limits + -2. **Batch publishing total size** (15% of cases) +2. **Batch publishing total size** (20% of cases) - Combined size of all messages in batch exceeds limit - Individual messages may be within limit but total exceeds it - + - Difficult to identify which specific message caused the error + - Batch of up to 1000 messages must fit within size limit + 3. **LiveObjects aggregate size** (5% of cases) - Total size of all object messages exceeds limit - State synchronization messages aggregate toward limit - + - Common in collaborative applications with large shared state + + +4. **REST vs WebSocket transport differences** (5% of cases) + - REST operations have ~350KB practical limit + - WebSocket connections support up to 2MB (2,097,152 bytes) + - Different validation points for different transports + ## Resolution Steps 1. **Identify your current size limit** - Check your Ably dashboard for your package tier - - Basic: 16KB, Standard: 64KB, Enterprise: Custom (up to 256KB) - - See [Ably pricing limits documentation](https://ably.com/docs/platform/pricing/limits#app-limits) - + - Free/Standard: 64KB (65,536 bytes) + - Pro: 256KB (262,144 bytes) + - Enterprise: Custom limit (negotiable) + - WebSocket connections may support up to 2MB regardless of tier + - See [Ably pricing](https://ably.com/pricing) for current limits + 2. **Reduce message size** - Remove unnecessary fields from your data - Compress data before sending (consider gzip for text) - Use more efficient data formats (binary instead of JSON where appropriate) - + - Consider external storage for large payloads with reference messages + 3. **For batch publishing** - - Split large batches into smaller groups + - Split large batches into smaller groups (max 1000 messages per batch) - Monitor combined size of all messages in batch + - Include unique IDs for each message to identify failures - Note: The error applies to total batch size, not individual messages - - -4. **For large data requirements** - - Consider splitting data across multiple messages + - See [message publishing documentation](https://ably.com/docs/messages) + + +4. **For LiveObjects** + - Monitor aggregate size of all object messages + - Split state updates into smaller chunks + - Consider reducing the frequency of state synchronization + - Use incremental updates instead of full state snapshots + + +5. **For large data requirements** + - Consider splitting data across multiple messages with sequence numbers - Use pagination for large datasets - - Store large content externally and send references - - Upgrade to a higher package tier if consistently hitting limits - - -5. **Implement client-side validation** - - Check message size before sending to avoid network round-trip - - Calculate total size including metadata overhead + - Store large content externally (e.g., S3, CDN) and send references + - Upgrade to Pro tier for 256KB limit or Enterprise for custom limits + + +6. **Implement client-side validation** + ```javascript + // Check message size before sending + const encoder = new TextEncoder(); + const messageSize = encoder.encode(JSON.stringify(message)).length; + const maxSize = 65536; // 64KB for Standard tier + + if (messageSize > maxSize) { + console.error(`Message too large: ${messageSize} bytes (max: ${maxSize})`); + // Handle oversized message + } + ``` + - Calculate total size including metadata overhead (approximately 12-20 bytes) - Provide user feedback before attempting to publish - + - For batch messages, validate total batch size + ## Automatic Handling Ably SDKs validate message size client-side before sending to prevent unnecessary network requests. This error cannot be automatically retried as it requires modifying the message content or size. - + ## Prevention -- **Monitor message sizes**: Track typical message sizes in your application -- **Set application limits**: Validate content size before creating messages +- **Monitor message sizes**: Track typical and peak message sizes in your application +- **Set application limits**: Validate content size before creating messages - **Use compression**: Compress large text payloads before sending - **Design for limits**: Structure your data model with size limits in mind - **Regular testing**: Test with production-like data volumes - +- **Consider transport**: Use WebSocket for larger messages when possible (up to 2MB) +- **Batch wisely**: When using batch publishing, monitor total batch size not just individual message sizes +- **Implement gradual degradation**: Automatically compress or summarize data when approaching limits + ## Performance Impact @@ -112,15 +151,115 @@ This error prevents message publishing but doesn't affect: - Other channels or messages - Message consumption by subscribers -However, batch publishing failures may require resending the entire batch after size adjustment. - +However, batch publishing failures require resending the entire batch after size adjustment, which can impact throughput. + + +## Known Issues + +### Batch Publishing Identification +When batch publishing fails with this error, identifying which specific message exceeded the limit can be challenging as the messageId may be null in error responses. Include unique identifiers in your messages to help track failures. + + +### Size Calculation +The size limit includes both your data payload and message metadata overhead (typically 12-20 bytes). Account for this when calculating message sizes. The exact overhead depends on: +- Message name length +- Client ID +- Connection ID +- Timestamp +- Any custom metadata + + +### Zero-Byte Anomaly +In rare cases, you might see "size was 0 bytes" errors. This typically indicates an encoding issue or empty message body. If you encounter this, verify your message serialization and contact support if the issue persists. + + +## Code Examples + +### Handling Size Limits in JavaScript +```javascript +// Helper function to check message size +function getMessageSize(message) { + const encoder = new TextEncoder(); + return encoder.encode(JSON.stringify(message)).length; +} + +// Publish with size validation +async function publishWithSizeCheck(channel, message) { + const maxSize = 65536; // 64KB for Standard tier + const size = getMessageSize(message); + + if (size > maxSize) { + // Option 1: Compress the message + const compressed = await compressMessage(message); + if (getMessageSize(compressed) <= maxSize) { + return channel.publish('compressed', compressed); + } + + // Option 2: Split into chunks + const chunks = splitIntoChunks(message, maxSize); + return Promise.all(chunks.map(chunk => + channel.publish('chunk', chunk) + )); + } + + return channel.publish('message', message); +} +``` + + +### Batch Publishing with Size Monitoring +```javascript +// Batch publish with size tracking +async function batchPublishWithSizeLimit(channel, messages) { + const maxBatchSize = 65536; // Total size limit + const batches = []; + let currentBatch = []; + let currentSize = 0; + + for (const message of messages) { + const messageSize = getMessageSize(message); + + if (currentSize + messageSize > maxBatchSize) { + // Current batch would exceed limit, start new batch + if (currentBatch.length > 0) { + batches.push(currentBatch); + } + currentBatch = [message]; + currentSize = messageSize; + } else { + currentBatch.push(message); + currentSize += messageSize; + } + } + + if (currentBatch.length > 0) { + batches.push(currentBatch); + } + + // Publish each batch separately + for (const batch of batches) { + await channel.publish(batch); + } +} +``` + ## Related Resources -- [Ably pricing and limits](https://ably.com/docs/platform/pricing/limits#app-limits) -- [Message batching documentation](https://ably.com/docs/rest/messages#batch) -- [LiveObjects documentation](https://ably.com/docs/products/liveobjects) -- [Compression best practices](https://ably.com/docs/best-practice#compression) +- [Ably pricing and limits](https://ably.com/pricing) +- [Ably Messages documentation](https://ably.com/docs/messages) +- [REST API Reference](https://ably.com/docs/api/rest-api) + +## Related Errors + +• **[40000 - Bad Request](https://help.ably.io/error/40000)** + General client error that may occur alongside size validation issues when message format is also invalid + +• **[40011 - Invalid Message Data](https://help.ably.io/error/40011)** + Related validation error for message content format issues, often occurs when trying to work around size limits + +• **[40013 - Invalid Message ID](https://help.ably.io/error/40013)** + May occur when batch messages have identification issues or when implementing chunking strategies ## Need Further Help? @@ -141,44 +280,80 @@ Our team will help you resolve this issue as quickly as possible. - + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/40010-invalid-channel-name.mdx b/src/pages/docs/platform/errors/codes/40010-invalid-channel-name.mdx index 1ea890eabc..5b211b9058 100644 --- a/src/pages/docs/platform/errors/codes/40010-invalid-channel-name.mdx +++ b/src/pages/docs/platform/errors/codes/40010-invalid-channel-name.mdx @@ -1,13 +1,13 @@ - + - + # Error 40010: Invalid channel name @@ -27,6 +27,7 @@ The channel name you provided doesn't meet Ably's naming requirements or contain - Remove any square brackets `[` from the start of your channel name - Ensure your channel name isn't empty or contains only special characters like `:` - Check that you're not mixing incompatible channel qualifiers +- Validate channel names match the expected format for your use case ## Error Messages @@ -44,25 +45,25 @@ You may see one of these messages: ## Common Causes 1. **Channel name starts with square brackets** (60% of cases) - + - Using `[` at the beginning of the channel name - Square brackets are reserved for channel qualifiers - Example: `[mychannel]` instead of `mychannel` 2. **Empty or invalid channel names** (20% of cases) - + - Using just `:` as a channel name - Empty channel names - - Channel names with only special characters + - Channel names with only special characters like `:::` 3. **Incompatible channel qualifiers** (15% of cases) - + - Trying to use derived options with already-qualified channels - Using qualifiers that don't support client attachment - Mixing incompatible qualifier types 4. **Malformed resource identifiers** (5% of cases) - + - Invalid scope format in resource IDs - Invalid directives in resource names - Malformed qualifier strings @@ -70,44 +71,56 @@ You may see one of these messages: ## Resolution Steps 1. **Fix channel names starting with square brackets** - + ```javascript // ❌ Wrong: Square brackets at the start const channel = ably.channels.get('[mychannel]'); + const channel = ably.channels.get('[chat-room]'); // ✅ Correct: No leading square brackets const channel = ably.channels.get('mychannel'); + const channel = ably.channels.get('chat-room'); - // ✅ Correct: Qualifiers use specific syntax + // ✅ Correct: Proper qualifier syntax const metaChannel = ably.channels.get('[meta]mychannel'); + const filteredChannel = ably.channels.get('[filter=headers.user==123]mychannel'); ``` 2. **Ensure channel names are valid** - + ```javascript // ❌ Wrong: Empty or special character only names const channel1 = ably.channels.get(':'); const channel2 = ably.channels.get(''); + const channel3 = ably.channels.get(':::'); // ✅ Correct: Valid channel names const channel1 = ably.channels.get('chat-room'); const channel2 = ably.channels.get('user-123-updates'); const channel3 = ably.channels.get('channel with spaces'); // Spaces are allowed + const channel4 = ably.channels.get('私のチャンネル'); // Unicode characters allowed ``` -3. **Check qualifier compatibility** - +3. **Use channel qualifiers correctly** + ```javascript - // ❌ Wrong: Mixing incompatible qualifiers + // ❌ Wrong: Mixing incompatible qualifiers or incorrect syntax // Don't try to add derived options to already-qualified channels + const wrongChannel = ably.channels.get('[meta][filter]channel'); // ✅ Correct: Use qualifiers as documented const metaChannel = ably.channels.get('[meta]channel'); const filteredChannel = ably.channels.get('[filter=headers.user-id==123]channel'); + const persistedChannel = ably.channels.get('[persisted]channel'); + + // ✅ Correct: Channel options for derived channels + const derivedChannel = ably.channels.getDerived('baseChannel', { + filter: 'headers.user-id==123' + }); ``` 4. **Validate channel names before use** - + ```javascript function validateChannelName(name) { // Channel names cannot start with '[' @@ -115,8 +128,8 @@ You may see one of these messages: throw new Error('Channel names cannot start with square brackets'); } // Channel names cannot be empty or just special characters - if (!name || name === ':') { - throw new Error('Invalid channel name'); + if (!name || name === ':' || /^:+$/.test(name)) { + throw new Error('Invalid channel name: cannot be empty or only colons'); } return true; } @@ -130,27 +143,80 @@ You may see one of these messages: } ``` +5. **Handle third-party integration channel names** + + If you're integrating with services like PubNub or other messaging platforms, transform their channel names to meet Ably's requirements: + ```javascript + // Transform channel names from other services + function transformChannelName(externalName) { + // Remove leading brackets if present + let ablyName = externalName.replace(/^\[/, ''); + + // Remove or replace invalid patterns + ablyName = ablyName.replace(/^:+$/, 'default-channel'); + + // Ensure it's not empty + if (!ablyName) { + ablyName = 'default-channel'; + } + + return ablyName; + } + + // Example with PubNub channel name format + const pubNubChannel = 'LANGUAGE_CHANNEL-ed9b69aa-f0c5-45ae-a80e-298c6c7e82a2'; + const ablyChannel = transformChannelName(pubNubChannel); + ``` + ## Automatic Handling -This is a client error that will not be automatically retried. You must fix the channel name format before the operation will succeed. +This is a client error that will not be automatically retried. You must fix the channel name format before the operation will succeed. The SDK will not attempt to correct invalid channel names automatically. ## Channel Naming Rules - + According to Ably's channel naming requirements: -- Channel names can contain any Unicode character, including spaces -- Channel names **cannot** start with square brackets `[` -- Square brackets are reserved for channel qualifiers (metadata/instructions to Ably) -- Valid qualifiers include `[meta]`, `[filter]`, `[persisted]`, and others +- **Allowed**: Any Unicode character, including spaces and non-ASCII characters +- **NOT allowed**: Channel names starting with square brackets `[` +- **Reserved**: Square brackets are reserved for channel qualifiers (metadata/instructions to Ably) +- **Invalid**: Empty channel names or names consisting only of special characters like `:` or `:::` + +### Valid Channel Qualifiers +- `[meta]` - Metadata channel for channel lifecycle events +- `[filter]` - Filter messages based on headers or attributes +- `[persisted]` - Enable message persistence +- `[?rewind=]` - Replay last n messages or time period For complete channel naming documentation, see [Channel naming documentation](https://ably.com/docs/channels#name-syntax). +## Prevention + +- **Input Validation**: Always validate user-provided channel names before using them +- **Third-Party Integration**: Transform external service channel names to meet Ably's requirements +- **Naming Convention**: Use consistent naming patterns across your application +- **Namespacing**: Consider using namespaces to organize channels (e.g., `chat:room-123`, `presence:user-456`) +- **Testing**: Include channel name validation in your test suite + ## Related Resources - [Channel documentation](https://ably.com/docs/channels) - [Channel qualifiers](https://ably.com/docs/channels#qualifiers) - [Channel naming restrictions](https://knowledge.ably.com/what-restrictions-are-there-on-channel-names) -- Related errors: [40000](./40000-bad-request.md), [40400](./40400-not-found.md) +- [Channel options and parameters](https://ably.com/docs/channels#options) + +## Related Errors + +• **[40000 - Bad Request](https://help.ably.io/error/40000)** + General client error that may occur with other invalid request parameters + +• **[40400 - Not Found](https://help.ably.io/error/40400)** + Occurs when referencing a channel that doesn't exist in certain contexts + +• **[90000 - Channel Operation Failed](https://help.ably.io/error/90000)** + Related channel operation failures that may cascade from invalid names + +• **[91000 - Unable to Enter Presence](https://help.ably.io/error/91000)** + May occur if trying to enter presence on a channel with an invalid name ## Need Further Help? @@ -171,44 +237,52 @@ Our team will help you resolve this issue as quickly as possible. - + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/40011-stale-ring-state.mdx b/src/pages/docs/platform/errors/codes/40011-stale-ring-state.mdx index 1a6438f851..1380c84f84 100644 --- a/src/pages/docs/platform/errors/codes/40011-stale-ring-state.mdx +++ b/src/pages/docs/platform/errors/codes/40011-stale-ring-state.mdx @@ -1,13 +1,13 @@ - + - + # Error 40011: Stale ring state or invalid data payload @@ -31,94 +31,178 @@ This error has two distinct causes: either the channel enumeration API encounter ## Error Messages You may see one of these messages: -- "stale ring state" - Channel enumeration pagination became invalid +- "stale ring state" - Channel enumeration pagination became invalid due to cluster changes - "Invalid data payload" - Message data type not supported (Python SDK) +- "Unable to continue query stale ring state" - Historical variant of enumeration error ## Common Causes ### 1. Channel Enumeration Pagination Issue (Most Common) - + When using the [channel enumeration API](https://ably.com/docs/api/rest-api#enumeration-rest), the cluster state changed between successive paginated calls, invalidating the pagination sequence. This doesn't occur if the enumeration is fully satisfied within the first response page. +**Why this happens**: +- Ably's distributed architecture can change cluster topology for scaling or maintenance +- Pagination cursors become invalid when the underlying cluster state changes +- This is a known limitation of the current enumeration API design + ### 2. Invalid Message Data Type (Python SDK) - + In the Python SDK, attempting to publish a message with unsupported data types. Supported types are: bytes, str, list, dict, bytearray, or None. +**Common triggers**: +- Publishing raw numbers (integers or floats) +- Attempting to send custom Python objects +- Using unsupported primitive types + ## Resolution Steps ### For Channel Enumeration Issues 1. **Restart the enumeration** - + - When you receive this error, start the enumeration again from the beginning - The cluster state has changed, making your current pagination cursor invalid + - This is the only way to get a complete, consistent result 2. **Optimize your enumeration strategy** + - Request larger page sizes to minimize pagination needs + - Use the maximum allowed page size to potentially get all results in one request - Consider caching enumeration results with an appropriate TTL - Implement automatic retry logic that restarts from the beginning 3. **Handle the error gracefully** ```javascript // Example retry logic for channel enumeration - async function enumerateChannels() { - try { - // Your enumeration logic here - } catch (error) { - if (error.code === 40011) { - // Restart enumeration from beginning - return enumerateChannels(); + async function enumerateChannelsWithRetry(maxAttempts = 3) { + for (let attempt = 1; attempt <= maxAttempts; attempt++) { + try { + const channels = []; + let hasMore = true; + let cursor = null; + + while (hasMore) { + const response = await fetch(`/channels?cursor=${cursor || ''}`); + if (response.status === 400 && response.error?.code === 40011) { + throw new Error('Stale ring state'); + } + + channels.push(...response.channels); + cursor = response.cursor; + hasMore = response.hasMore; + } + + return channels; + } catch (error) { + if (error.message === 'Stale ring state' && attempt < maxAttempts) { + console.log(`Enumeration failed, retrying (attempt ${attempt + 1}/${maxAttempts})`); + continue; + } + throw error; } - throw error; } } ``` - + ### For Invalid Data Payload (Python SDK) 1. **Validate your message data type** - + - Ensure your data is one of: bytes, str, list, dict, bytearray, or None - Primitive numbers and custom objects are not directly supported + - The validation happens before the message is sent to Ably 2. **Convert unsupported types** ```python - # Convert numbers to strings or include in dict - # ❌ Wrong: Publishing a raw number + # ❌ Wrong: Publishing raw numbers or custom objects channel.publish('event', 42) # Will raise error 40011 + channel.publish('event', 3.14) # Will raise error 40011 + channel.publish('event', MyCustomClass()) # Will raise error 40011 - # ✅ Correct: Convert to supported type + # ✅ Correct: Convert to supported types channel.publish('event', str(42)) # As string channel.publish('event', {'value': 42}) # In dict + channel.publish('event', json.dumps({'pi': 3.14})) # JSON string + channel.publish('event', bytes([42])) # As bytes + ``` + + +3. **Implement type checking before publishing** + ```python + def safe_publish(channel, event_name, data): + """Safely publish data with type validation""" + # Convert common unsupported types + if isinstance(data, (int, float, bool)): + data = {'value': data} # Wrap in dict + elif hasattr(data, '__dict__'): # Custom object + data = data.__dict__ # Convert to dict + + # Now publish + try: + channel.publish(event_name, data) + except AblyException as e: + if e.code == 40011: + print(f"Unsupported data type: {type(data)}") + raise ``` - + ## Automatic Handling -This is a client error that will not be automatically retried. You must: +This is a client error that will not be automatically retried by Ably SDKs. You must: - For enumeration: Restart from the beginning - For data validation: Fix the data type before retrying +The SDKs do not implement automatic retry for this error because: +- Enumeration requires a fresh start, not a simple retry +- Data validation errors need code changes to resolve + ## Prevention ### Channel Enumeration - -- Request larger page sizes to complete enumeration in a single request when possible -- Build retry logic into your enumeration code -- Consider whether you need real-time enumeration or if cached results would suffice + +- **Request maximum page sizes**: Use the largest allowed page size to minimize pagination +- **Build retry logic**: Always implement enumeration restart logic in production code +- **Consider alternatives**: Evaluate if you need real-time enumeration or if cached results would suffice +- **Monitor frequency**: If you frequently encounter this error, consider architectural changes + +### Message Publishing (Python) +- **Validate early**: Check data types before attempting to publish +- **Use type hints**: Leverage Python's type system to catch issues during development +- **Standardize serialization**: Always convert complex data to dicts or JSON strings +- **Test edge cases**: Include various data types in your test suite + +## Performance Impact + +### Channel Enumeration +- Restarting enumeration adds latency to your operation +- Multiple retries can significantly impact response times +- Consider implementing progressive backoff between retry attempts ### Message Publishing -- Always validate data types before publishing -- Use SDK-appropriate data structures -- Implement type checking in your application code +- Type validation errors prevent message sending entirely +- No performance impact beyond the failed operation +- Fixing data types is typically a quick code change ## Related Resources - [Channel Enumeration API](https://ably.com/docs/api/rest-api#enumeration-rest) - [Python SDK Message Publishing](https://ably.com/docs/realtime/messages#publish) +- [Message Structure and Types](https://ably.com/docs/realtime/messages#message-structure) - [Ably API Error Codes](https://ably.com/docs/platform/errors/codes) -- Related errors: [40000](./40000-bad-request.md) (Bad Request), [40013](./40013-invalid-message-data.md) (Invalid message data) + +## Related Errors + +• **[40000 - Bad Request](https://help.ably.io/error/40000)** + General validation errors that may include similar data type issues + +• **[40003 - Invalid Request](https://help.ably.io/error/40003)** + Invalid parameter values in API requests + +• **[40013 - Invalid Message Data](https://help.ably.io/error/40013)** + Broader message validation errors including encoding issues ## Need Further Help? @@ -139,40 +223,61 @@ Our team will help you resolve this issue as quickly as possible. - + + + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/40012-invalid-client-id.mdx b/src/pages/docs/platform/errors/codes/40012-invalid-client-id.mdx index 2697e623b9..6f7ae3a514 100644 --- a/src/pages/docs/platform/errors/codes/40012-invalid-client-id.mdx +++ b/src/pages/docs/platform/errors/codes/40012-invalid-client-id.mdx @@ -1,13 +1,13 @@ - + - + # Error 40012: Invalid client ID @@ -28,21 +28,24 @@ Your request contains a client ID that doesn't meet Ably's validation requiremen - Ensure your client ID is a non-empty string (not "" or null in messages) - Don't use "*" as a client ID except in token parameters for wildcard capability - For Laravel Echo users: Check compatibility with Pusher protocol adapter +- For presence operations: Always set a client ID before entering/leaving channels ## Error Messages You may see one of these messages: -- "invalid client id" -- "clientId can't be an empty string" -- "clientId must be either a string or null" -- "Can't use \"*\" as a clientId as that string is reserved" -- "clientId provided in ClientOptions must match clientId in token" -- "Incompatible clientId specified in message" -- "clientId must be specified to enter or leave a presence channel" -- "invalid clientId; must be base64 encoded if passed by header" -- "Malformed message; no clientId in message or inferred from connection" -- "Invalid client ID provided" -- "Wildcard client_id is reserved and cannot be used when publishing messages" +- "invalid client id" - Generic validation failure +- "clientId can't be an empty string" - Empty string provided as client ID +- "clientId must be either a string or null" - Invalid type provided +- "Can't use \"*\" as a clientId as that string is reserved" - Wildcard misuse +- "clientId provided in ClientOptions must match clientId in token" - Configuration mismatch +- "Incompatible clientId specified in message" - Message client ID conflicts with auth +- "clientId must be specified to enter or leave a presence channel" - Missing for presence +- "invalid clientId; must be base64 encoded if passed by header" - Encoding issue +- "Malformed message; no clientId in message or inferred from connection" - Server-side validation failure +- "Invalid client ID provided" - General validation failure +- "Wildcard client_id is reserved and cannot be used when publishing messages" - Python-specific wildcard error +- "Client ID provided doesn't match existing authenticated client ID" - Go SDK mismatch error +- "Invalid client ID in API key" - .NET parsing error ## Common Causes @@ -50,36 +53,42 @@ You may see one of these messages: - Using "" instead of a proper string value - Not setting client ID when required for presence - Empty string in token requests - + - Validated across all SDKs and server + 2. **Client ID mismatch** (30% of cases) - Token client ID differs from configured client ID - Message client ID conflicts with authenticated client ID - Client options specify different client ID than token - + - Common during auth upgrades or token refresh + 3. **Wildcard "*" misuse** (20% of cases) - Using "*" as a regular client ID instead of in token parameters - Attempting to initialize REST client with wildcard client ID - Wildcard in request headers or URLs - + - PHP SDK specifically blocks REST initialization with wildcard + 4. **Missing client ID for presence** (10% of cases) - Attempting presence operations without authenticated client ID - Not setting client ID before enter/leave/update operations - + - Presence channel requirements not met + 5. **Invalid type or encoding** (5% of cases) - Client ID is not a string or null - Missing base64 encoding when passed via header - Non-string values in JWT tokens - + - Server-side validation failures + ## Resolution Steps 1. **For empty client ID errors** - Provide a non-empty string for your client ID - If client ID is optional in your context, use null instead of "" + - Validate before sending to Ably ```javascript // ❌ Wrong: Empty string const ably = new Ably.Realtime({ clientId: '' }); @@ -89,10 +98,11 @@ You may see one of these messages: // or const ably = new Ably.Realtime({ /* no clientId */ }); ``` - + 2. **For client ID mismatch errors** - - Ensure your token and client options use the same client ID: + - Ensure your token and client options use the same client ID + - Let the token set the client ID rather than overriding in options ```javascript // ❌ Wrong: Mismatched client IDs const ably = new Ably.Realtime({ @@ -106,10 +116,11 @@ You may see one of these messages: // Client ID will be set from token }); ``` - + 3. **For wildcard client ID errors** - - Use wildcard only in token parameters, not as regular client ID: + - Use wildcard only in token parameters, not as regular client ID + - Wildcard enables publishing on behalf of any client ```javascript // ❌ Wrong: Using wildcard as regular client ID const ably = new Ably.Rest({ clientId: '*' }); @@ -120,10 +131,11 @@ You may see one of these messages: capability: { '*': ['publish', 'subscribe'] } }); ``` - + 4. **For presence operations** - - Always set client ID before presence operations: + - Always set client ID before presence operations + - Configure via authentication or client options ```javascript // ❌ Wrong: No client ID for presence const ably = new Ably.Realtime({ key: 'your-api-key' }); @@ -136,10 +148,11 @@ You may see one of these messages: }); channel.presence.enter(); // Will succeed ``` - + 5. **For publishing messages** - - Don't set client ID in messages when already authenticated: + - Don't set client ID in messages when already authenticated + - Client ID is automatically populated from authentication ```javascript // ❌ Wrong: Manually setting client ID in message channel.publish({ @@ -155,11 +168,11 @@ You may see one of these messages: // Client ID is set automatically from authentication }); ``` - + 6. **For header encoding issues** - - When using X-Ably-Clientid header, base64 encode the value - - Alternatively, use query parameter clientId (no encoding needed) + - Base64 encode when using X-Ably-Clientid header + - Alternatively, use query parameter (no encoding needed) ```bash # ❌ Wrong: Plain text in header curl -H "X-Ably-Clientid: user-123" ... @@ -170,14 +183,29 @@ You may see one of these messages: # ✅ Or use query parameter curl "https://rest.ably.io/channels/test?clientId=user-123" ... ``` - + 7. **For Laravel Echo with Pusher Protocol** - - If using Laravel Echo with Ably's Pusher protocol adapter and experiencing presence issues: - - Ensure your client ID format is compatible with Pusher protocol expectations - - Consider using native Ably SDK instead of Pusher protocol adapter for presence channels - - Verify your Laravel Echo configuration matches Ably's requirements - + - Known compatibility issue with presence channels + - Consider using native Ably SDK instead of Pusher adapter + - Ensure client ID format matches Pusher expectations + - Test presence functionality thoroughly + + +8. **For type validation errors** + - Ensure client ID is string or null (not undefined, number, or object) + - Validate types before SDK operations + ```javascript + // ❌ Wrong: Invalid types + clientId: undefined // Not allowed + clientId: 123 // Must be string + clientId: {} // Must be string + + // ✅ Correct: Valid types + clientId: 'user-123' // String + clientId: null // Null is allowed + ``` + ## Automatic Handling @@ -191,23 +219,57 @@ This is a client error that will not be automatically retried. You must fix the - **Presence**: Always configure clientId before attempting presence operations - **Validation**: Ensure clientId is either a non-empty string or null (not undefined or other types) - **Laravel Echo**: Test presence channels thoroughly when using Pusher protocol adapter +- **Headers**: Always base64 encode clientId when using X-Ably-Clientid header ## SDK-Specific Behaviors -Different Ably SDKs may show slightly different error messages: -- **JavaScript**: Most comprehensive validation with specific messages for each scenario -- **Java**: Uses "Incompatible clientId" terminology -- **Python**: Includes actual values in error messages for debugging -- **Ruby**: May throw IncompatibleClientId exception -- **PHP**: Specifically validates against wildcard in REST context -- **.NET**: Reports "Invalid client ID in API key" for parsing errors -- **Go**: Provides detailed mismatch information +Different Ably SDKs have slightly different validation and error messages: + +- **JavaScript (ably-js)**: Most comprehensive validation with specific messages for each scenario + - Validates type, empty string, wildcard, and presence requirements + - Clear error messages for debugging +- **Java (ably-java)**: Uses "Incompatible clientId" terminology + - Focus on message/auth compatibility +- **Python (ably-python)**: Includes actual values in error messages + - Shows both attempted and configured client IDs for debugging +- **Ruby (ably-ruby)**: Defines custom IncompatibleClientId exception + - Connection manager validates client ID during connection +- **PHP (ably-php)**: Specifically blocks wildcard in REST context + - Prevents REST client initialization with "*" client ID +- **.NET (ably-dotnet)**: Reports "Invalid client ID in API key" + - Additional validation during API key parsing +- **Go (ably-go)**: Provides detailed mismatch information + - Shows both existing and requested client IDs +- **Rust (ably-rust)**: Combined validation for wildcard and empty string + - Single error for both conditions + +## Performance Impact + +This error prevents the operation but doesn't affect: +- Existing connections (unless during connection establishment) +- Other channels or presence sets +- Message delivery for properly authenticated clients +- Overall system performance + +## Related Errors + +• **[40102 - Token expired](https://help.ably.io/error/40102)** + Authentication token has expired and needs renewal - may occur alongside 40012 if new token has different client ID + +• **[40103 - Invalid use of basic auth over non-TLS](https://help.ably.io/error/40103)** + Related authentication error when using basic auth incorrectly + +• **[40140-40149 - Token error range](https://help.ably.io/error/40140)** + Various token-related errors that may involve client ID validation + +• **[91000 - Unable to enter presence](https://help.ably.io/error/91000)** + Specific presence error that often relates to missing or invalid client ID ## Related Resources - [Authentication documentation](https://ably.com/docs/auth) -- [Client ID explained](https://ably.com/docs/auth/identified-clients) -- [Presence documentation](https://ably.com/docs/presence) +- [Identified clients documentation](https://ably.com/docs/auth/identified-clients) +- [Presence documentation](https://ably.com/docs/realtime/presence) - [Token authentication](https://ably.com/docs/auth/token) - [Laravel Echo integration](https://ably.com/docs/general/laravel-echo) @@ -231,46 +293,51 @@ Our team will help you resolve this issue as quickly as possible. - + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/40013-invalid-message-data-or-encoding.mdx b/src/pages/docs/platform/errors/codes/40013-invalid-message-data-or-encoding.mdx index 86bb1781af..03eae76078 100644 --- a/src/pages/docs/platform/errors/codes/40013-invalid-message-data-or-encoding.mdx +++ b/src/pages/docs/platform/errors/codes/40013-invalid-message-data-or-encoding.mdx @@ -1,13 +1,13 @@ - + - + # Error 40013: Invalid message data or encoding @@ -27,6 +27,7 @@ The SDK cannot encode or decode your message because the data type is unsupporte - Ensure message data is a string, buffer, JSON-serializable object, or array - For encrypted channels, verify cipher configuration is consistent across clients - Consider marshalling complex data as JSON before publishing +- Check for race conditions with dynamically constructed channel names ## Error Messages @@ -37,39 +38,46 @@ You may see one of these messages: - "Map value data type is unsupported" (LiveObjects) - "Invalid data type for 'base64' decoding" - "Invalid data type for 'json' decoding" +- "Invalid data type for 'utf-8' decoding" - "decrypt failed" - "Error processing the {encoding} encoding, decoder returned '{error}'" +- "Invalid cipher message data; unexpected length: {}" (Rust) +- "unknown encoding: '{encoding}'" ## Common Causes 1. **Unsupported data types** (60% of cases) - + - Publishing objects that aren't JSON-serializable - Using LiveObjects with unsupported value types - Passing wrong argument types to publish() + - Platform-specific type mismatches (e.g., NSString vs NSData in iOS) 2. **Encryption/decryption failures** (30% of cases) - + - Cipher configuration mismatch between clients - Decryption failures after channel idle periods - Race conditions with encryption key handling + - Inconsistent encryption for presence vs message data 3. **Encoding chain failures** (10% of cases) - + - Invalid base64 data - Malformed JSON strings - UTF-8 encoding of binary data + - Cipher block alignment issues (Rust SDK) ## Resolution Steps 1. **Validate your message data type** - + Supported types vary by SDK: - **JavaScript**: String, Buffer, JSON-serializable objects/arrays - **Ruby**: String, Hash, Array, or nil - **iOS/macOS**: NSString, NSData, NSArray, NSDictionary - **Java**: String, byte[], JsonElement + - **Rust**: Types that implement Serialize trait For complex objects, serialize to JSON first: ```javascript @@ -79,10 +87,10 @@ You may see one of these messages: // ✅ Correct: Serialize to JSON first channel.publish('update', JSON.stringify(myComplexObject)); ``` - + 2. **Fix publish() method arguments** (JavaScript SDKs) - + ```javascript // ❌ Wrong: Invalid single argument @@ -97,7 +105,7 @@ You may see one of these messages: 3. **Verify encryption configuration** - + If using encrypted channels, ensure all clients use identical cipher configuration: ```javascript @@ -106,11 +114,15 @@ You may see one of these messages: const channel = ably.channels.get('encrypted-channel', { cipher: { key: cipherKey } }); + + // For dynamic channel names, memoize to avoid race conditions + const channelName = getChannelName(); // Memoize this! + const channel = ably.channels.get(channelName, { cipher: { key } }); ``` - + 4. **Handle LiveObjects data types** - + For LiveObjects, only use supported types: ```javascript @@ -123,24 +135,69 @@ You may see one of these messages: ``` +5. **SDK-Specific Considerations** + + + **iOS/macOS**: Ensure correct type usage: + ```objc + // ❌ Wrong: Using NSString for base64 + [channel publish:@"event" data:stringData]; + + // ✅ Correct: Use NSData for binary + NSData *data = [stringData dataUsingEncoding:NSUTF8StringEncoding]; + [channel publish:@"event" data:data]; + ``` + + **Rust**: Ensure cipher block alignment: + ```rust + // Encrypted data must be block-aligned (16 bytes for AES) + assert!(encrypted_data.len() % 16 == 0); + ``` + ## Automatic Handling This is a client error that will not be automatically retried. The SDK cannot recover from invalid data types or encoding failures - you must fix the data format or configuration before the operation will succeed. +## Known Production Issues + + + +### Idle Channel Encryption Issues +Some customers have experienced decryption failures after channels remain idle for extended periods. The issue typically resolves when reconnecting. If you encounter this: +- Monitor for patterns of idle period failures +- Consider implementing periodic keepalive messages +- Enable verbose logging to capture full context + +### Dynamic Channel Name Race Conditions +When using dynamically constructed channel names with encryption, race conditions can cause inconsistent encryption states. Always memoize channel names when using encryption. + ## Prevention - Always validate data types before publishing - Use explicit JSON serialization for complex objects - Maintain consistent cipher configuration across all clients +- Memoize channel names when using encryption to avoid race conditions - Test encoding/decoding with your specific data types in development - Enable verbose logging to capture full error context during debugging +- For production encrypted channels, implement monitoring for decryption failures + +## Related Errors + +• **[40000 - Bad Request](https://help.ably.io/error/40000)** + General bad request error that may occur alongside encoding issues + +• **[92001-92005 - Encryption Errors](https://help.ably.io/error/92001)** + Specific encryption configuration and cipher operation failures + +• **[80013 - Protocol Error](https://help.ably.io/error/80013)** + Protocol violations that may result from malformed encoded messages ## Related Resources -- [Message encoding documentation](https://ably.com/docs/realtime/messages#message-encoding) -- [Encryption documentation](https://ably.com/docs/realtime/encryption) -- [LiveObjects documentation](https://ably.com/docs/products/liveobjects) -- Related errors: [40000](./40000-bad-request.md) (general bad request), [92001-92005](./92001-encryption-error.md) (encryption-specific errors) +- [Message concepts documentation](https://ably.com/docs/messages/) +- [Encryption documentation](https://ably.com/docs/channels/options/encryption) +- [API Reference for Messages](https://ably.com/docs/api/rest-sdk/messages) +- [Channel options overview](https://ably.com/docs/channels/options) ## Need Further Help? @@ -154,6 +211,7 @@ When contacting support, please provide: - Steps to reproduce the issue - Any relevant code snippets (without sensitive credentials) - The SDK and version you're using +- Whether encryption is involved and if the issue occurs after idle periods Our team will help you resolve this issue as quickly as possible. @@ -162,33 +220,41 @@ Our team will help you resolve this issue as quickly as possible. + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/40014-resource-disposed.mdx b/src/pages/docs/platform/errors/codes/40014-resource-disposed.mdx index 8291a38cf9..14e381aa74 100644 --- a/src/pages/docs/platform/errors/codes/40014-resource-disposed.mdx +++ b/src/pages/docs/platform/errors/codes/40014-resource-disposed.mdx @@ -1,13 +1,13 @@ - + - + # Error 40014: Resource disposed @@ -25,9 +25,9 @@ The operation failed because the requested resource (such as a channel, connecti ## Quick Fix - Create a new instance of the resource (channel, connection) and retry the operation -- Implement retry logic with exponential backoff for transient disposal errors +- Implement simple retry logic for transient disposal errors (do NOT use exponential backoff) - Ensure you're not holding references to disposed resources - + ## Error Messages @@ -39,7 +39,9 @@ You may see one of these messages: - "Redis client disposed" - "Attachment disposed during preparation" - "Channel disposed" - +- "ClusteredKeySet disposed baseKey = [key]" +- "Coordinator client disposed" + ## Common Causes @@ -47,29 +49,34 @@ You may see one of these messages: - Channel was disposed while operations were in progress - Attach request was superseded by a detach request - Channel attachment was aborted before completion - + - Rapid channel activation causing timing conflicts + 2. **Service deployment or restart** (25% of cases) - Ably service deployments causing temporary resource disposal - Coordinator relocation during channel setup - Connection recycling during maintenance - + - Normal infrastructure operations + 3. **High-volume scenarios** (15% of cases) - - Redis connection disposal during high traffic + - Redis connection disposal during high traffic (8+ errors/second) - Presence validation occurring on disposed resources - Message rule operations on disposed ClusteredKeySet - + - Can generate 10k+ errors per day in production + ## Resolution Steps -1. **Implement retry logic for publish operations** - +1. **Implement simple retry logic for publish operations** + ```javascript + // Important: Do NOT use exponential backoff for this error + // This is a transient resource state, not a rate limit issue const publishWithRetry = () => { channel.publish(name, data, (err) => { if (err && err.code === 40014) { - // Resource was disposed, retry the operation + // Resource was disposed, immediately retry publishWithRetry(); return; } @@ -77,28 +84,33 @@ You may see one of these messages: }); }; ``` + 2. **For channel attachment errors** - - Detach and re-attach the channel - - Create a new channel instance if detach fails + - Detach the channel if still attached + - Re-attach the channel + - If detach fails, create a new channel instance - Ensure proper cleanup of old channel references - + 3. **For connection-level issues** - Create a new Ably client connection - Re-establish all channel subscriptions - Restore presence state if applicable + - Verify connection state before operations + 4. **Monitor and track occurrences** - Track frequency of 40014 errors as a system health indicator - High volumes (>8 errors/second) may indicate infrastructure issues - - Contact support if errors persist at high volume - + - Normal during deployments and service maintenance + - Contact support if errors persist at high volume outside maintenance windows + ## Automatic Handling -This error indicates a disposed resource and requires application-level handling. Ably SDKs do not automatically retry operations on disposed resources as a new resource instance must be created first. - +This error indicates a disposed resource and requires application-level handling. Ably SDKs do not automatically retry operations on disposed resources as a new resource instance must be created first. Unlike rate limit errors (429), this does NOT require exponential backoff - immediate retry is appropriate. + ## Prevention @@ -106,21 +118,38 @@ This error indicates a disposed resource and requires application-level handling - Avoid holding long-lived references to channels or connections - Implement graceful shutdown sequences for resources - Use connection state callbacks to track resource availability - +- Consider implementing connection pooling for high-volume scenarios + ## Performance Impact While this error is typically transient and recoverable: - May cause temporary message delivery delays during retry -- High volumes can indicate service degradation +- High volumes (>8/second) can indicate service degradation +- Can correlate with webhook delivery issues in extreme cases - Not typically user-facing unless retry logic is missing - + ## Related Resources -- [Channel lifecycle documentation](https://ably.com/docs/channels#attach-detach) -- [Connection state management](https://ably.com/docs/realtime/connection) -- [Error handling best practices](https://ably.com/docs/best-practice#error-handling) +- [Channel states documentation](https://ably.com/docs/channels/states) +- [Channel lifecycle events](https://ably.com/tutorials/channel-lifecycle-events) +- [Connection states](https://ably.com/docs/connect) +- [Realtime channels documentation](https://ably.com/docs/realtime/channels) + +## Related Errors + +• **[40000 - Bad Request](https://help.ably.io/error/40000)** + Can occur with suspended state or queueing disabled, similar resource unavailability + +• **[80000 - Connection Failed](https://help.ably.io/error/80000)** + Connection-level failure that may lead to resource disposal + +• **[80002 - Connection Suspended](https://help.ably.io/error/80002)** + Connection enters suspended state after prolonged disconnection, resources may be disposed + +• **[90000 - Channel Operation Failed](https://help.ably.io/error/90000)** + General channel operation failure that might be related to disposed resources ## Need Further Help? @@ -134,6 +163,7 @@ When contacting support, please provide: - Steps to reproduce the issue - Any relevant code snippets (without sensitive credentials) - The SDK and version you're using +- Frequency of errors (errors per second/minute) Our team will help you resolve this issue as quickly as possible. @@ -141,34 +171,40 @@ Our team will help you resolve this issue as quickly as possible. - + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/40015-invalid-device-id.mdx b/src/pages/docs/platform/errors/codes/40015-invalid-device-id.mdx index 6d6a373c1b..7a5954f3c3 100644 --- a/src/pages/docs/platform/errors/codes/40015-invalid-device-id.mdx +++ b/src/pages/docs/platform/errors/codes/40015-invalid-device-id.mdx @@ -1,13 +1,13 @@ - + - + # Error 40015: Invalid device ID @@ -25,8 +25,8 @@ The device ID provided in your push notification registration request doesn't me ## Quick Fix - Ensure your device ID is a non-empty string value -- Remove any non-string types (numbers, objects, arrays) -- Check that the device ID isn't an empty string +- Remove any non-string types (numbers, objects, arrays, null, undefined) +- Check that the device ID isn't an empty string or whitespace-only ## Error Messages @@ -39,24 +39,25 @@ You'll see this message: - Passing a number instead of string - Passing an object or array - Passing null or undefined - + 2. **Empty string device ID** (30% of cases) - Device ID is present but empty (`""`) - Whitespace-only string - + 3. **Missing device ID in registration** (10% of cases) - DeviceDetails object missing the ID property - Attempting to register without proper device identification - + ## Resolution Steps 1. **Verify device ID type and content** - Ensure the device ID is a string type - Confirm it contains actual characters (not empty) - + - Check for accidental type conversions + 2. **Check your DeviceDetails object structure** ```javascript @@ -70,39 +71,81 @@ You'll see this message: id: "" // Empty string }; + // ❌ Wrong: Null or undefined + const deviceDetails = { + id: null // Will trigger error + }; + // ✅ Correct: Valid device ID const deviceDetails = { id: "device-abc-123" // Non-empty string }; ``` - + 3. **Review the push registration parameters** - When registering for push notifications, provide either `deviceId` OR `clientId`, not both - If you receive error 40018, you're providing both parameters - If you receive error 40019, you're providing neither parameter - + - Ensure exactly one identifier is provided + 4. **Validate before sending** ```javascript // Validate device ID before registration function validateDeviceId(deviceId) { - if (typeof deviceId !== 'string' || deviceId === '') { - throw new Error('Device ID must be a non-empty string'); + if (typeof deviceId !== 'string') { + throw new Error('Device ID must be a string, got: ' + typeof deviceId); + } + if (deviceId === '') { + throw new Error('Device ID cannot be empty'); } return true; } + + // Use validation before API call + try { + validateDeviceId(myDeviceId); + // Proceed with registration + } catch (error) { + console.error('Invalid device ID:', error.message); + } ``` - + + +5. **Debug device ID issues** + - Log the type and value of your device ID before submission + - Check if any middleware or framework is modifying the value + - Verify that JSON serialization preserves the string type + ## Automatic Handling This is a client error that will not be automatically retried. You must fix the device ID format before the registration will succeed. +## Prevention + +- Always validate device IDs before registration attempts +- Use TypeScript or similar type systems to enforce string types +- Implement client-side validation matching server requirements +- Store device IDs as strings in your database/storage + +## Related Errors + +• **[40012 - Invalid Client ID](https://faqs.ably.com/error-code-40012-invalid-client-id)** + Similar validation error for client ID parameter in push registrations + +• **[40018 - Both IDs Provided](https://help.ably.io/error/40018)** + Occurs when both deviceId and clientId are specified - must provide exactly one + +• **[40019 - Neither ID Provided](https://help.ably.io/error/40019)** + Occurs when neither deviceId nor clientId is specified - one identifier is required + ## Related Resources -- [Push Notifications Documentation](https://ably.com/docs/push) -- [DeviceDetails API Reference](https://ably.com/docs/api/rest-sdk/push-admin#device-details) -- Related errors: [40012 (Invalid clientId)](https://help.ably.io/error/40012), [40018 (Both IDs provided)](https://help.ably.io/error/40018), [40019 (Neither ID provided)](https://help.ably.io/error/40019) + +- [Push Notifications Documentation](https://ably.com/docs/general/push) +- [Push Admin API Reference](https://ably.com/docs/api/rest-sdk/push-admin) +- [DeviceDetails Object Reference](https://ably.com/docs/api/rest-sdk/push-admin#device-details) ## Need Further Help? @@ -123,43 +166,51 @@ Our team will help you resolve this issue as quickly as possible. - + + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/40017-unsupported-protocol-version.mdx b/src/pages/docs/platform/errors/codes/40017-unsupported-protocol-version.mdx index 53adfb8815..59559cbc5d 100644 --- a/src/pages/docs/platform/errors/codes/40017-unsupported-protocol-version.mdx +++ b/src/pages/docs/platform/errors/codes/40017-unsupported-protocol-version.mdx @@ -1,20 +1,20 @@ - + - + # Error 40017: Unsupported protocol version ## What Happened -The request did not specify a protocol version or provided an invalid version in the request parameters. +Your request to Ably failed because it either didn't include a required protocol version parameter or specified an unsupported version number. ## Quick Reference @@ -24,57 +24,68 @@ The request did not specify a protocol version or provided an invalid version in ## Quick Fix -- Add `?v=1.1` or higher to SSE connection requests -- Ensure WebSocket connections use valid API versions -- Update to latest SDK version (SDK users won't see this error) +- Add `?v=1.2` (current version) to SSE connection URLs +- Verify your protocol version is supported (minimum v=1.1 for stateless) +- If using an SDK, this error indicates a configuration issue - SDKs handle versioning automatically ## Error Messages You may see one of these messages: - "Stateless connections must specify a protocol version (e.g. ?v=1.1)" -- "Invalid api version specified: [version]. See https://help.ably.io/error/40017" +- "Invalid api version specified: 3.0. See https://help.ably.io/error/40017" (example with version 3.0) - "Unsupported protocol version" + ## Common Causes 1. **Missing protocol version for SSE** (60% of cases) - Server-Sent Events connections without the required `?v=` parameter - - Direct API calls to SSE endpoints without version specification - + - Direct API calls to `/event-stream` or `/sse` endpoints without version + - EventSource connections missing version in URL + -2. **Invalid version format** (25% of cases) - - Incorrectly formatted version strings (e.g., "3.0" when not supported) - - Using version numbers not recognized by the platform - +2. **Unsupported version number** (25% of cases) + - Using version 3.0 for realtime connections (not initially supported) + - Specifying versions not yet available on the platform + - Mismatch between REST and realtime version support + 3. **Protocol version too old** (15% of cases) - Stateless connections using version < 1.1 - - Using deprecated protocol versions - + - SSE connections with v=1.0 or lower + - Legacy protocol versions no longer supported + ## Resolution Steps 1. **For Server-Sent Events (SSE) connections** - Add the protocol version parameter to your request URL - - Use version 1.1 or higher for stateless connections - - Example: `https://rest.ably.io/event-stream?v=1.1&key=YOUR_KEY` - + - Use version 1.2 (current) or minimum 1.1 for stateless connections + - Example: `https://realtime.ably.io/event-stream?v=1.2&channels=myChannel&key=YOUR_KEY` + - For EventSource API: Include version in the URL string + ```javascript + var url = 'https://realtime.ably.io/event-stream?channels=myChannel&v=1.2&key=' + apiKey; + var eventSource = new EventSource(url); + ``` + 2. **For WebSocket connections** - - Verify the API version specified in your connection parameters - - Check Ably documentation for supported version numbers - - Remove or correct any invalid version parameters - + - Verify the API version in your connection parameters + - Note that REST and realtime may support different version ranges + - If using version 3.0, check if it's supported for your connection type + -3. **For SDK users** +3. **For SDK users (this error is unexpected)** - Update to the latest SDK version - - SDKs automatically handle protocol versioning - - You should not encounter this error with properly configured SDKs - + - Verify your SDK initialization doesn't override default versioning + - Check if you're accidentally bypassing SDK connection management + - SDKs automatically handle protocol versioning - this error suggests misconfiguration + 4. **Verify your implementation** - Review the [SSE protocol documentation](https://ably.com/docs/protocols/sse) - - Check the [API versioning guide](https://ably.com/docs/api-versioning) + - Check current version requirements in [Connection documentation](https://ably.com/docs/connect/states) + - Test with v=1.2 (current recommended version) - Ensure all manual API calls include proper version parameters ## Automatic Handling @@ -89,18 +100,28 @@ SDK users are protected from this error as the SDK negotiates the appropriate pr ## Prevention -- **Always use official SDKs** when possible for automatic version handling -- **Include version parameters** in all manual SSE connection requests -- **Test protocol compatibility** before deploying custom implementations +- **Always use official SDKs** when possible - they handle version negotiation automatically +- **Include version parameters** in all manual SSE/EventSource connections (`?v=1.2`) +- **Test version compatibility** especially when using newer protocol versions like 3.0 - **Keep SDKs updated** to ensure support for latest protocol versions - +- **Document version requirements** in your connection code for future maintenance + ## Related Resources - [SSE Protocol Documentation](https://ably.com/docs/protocols/sse) +- [Connection Overview](https://ably.com/docs/connect/) +- [Connection States](https://ably.com/docs/connect/states) +- [API Reference - Connection](https://ably.com/docs/api/realtime-sdk/connection) - [Ably Protocol Specification](https://github.com/ably/specification) -- [Connection State Management](https://ably.com/docs/realtime/connection) -- Related errors: [80015](./80015-incompatible-connection-parameters.md) (connection parameter issues), [40021](./40021-newer-platform-version-required.md) (feature version requirements) + +## Related Errors + +• **[80015 - Incompatible Connection Parameters](https://help.ably.io/error/80015)** + Related connection parameter validation errors that may occur alongside version issues + +• **[40021 - Newer Platform Version Required](https://help.ably.io/error/40021)** + When a feature requires a more recent platform version than currently available ## Need Further Help? @@ -121,41 +142,47 @@ Our team will help you resolve this issue as quickly as possible. - + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/40018-delta-decode-failure.mdx b/src/pages/docs/platform/errors/codes/40018-delta-decode-failure.mdx index ce86598c74..1f69e07363 100644 --- a/src/pages/docs/platform/errors/codes/40018-delta-decode-failure.mdx +++ b/src/pages/docs/platform/errors/codes/40018-delta-decode-failure.mdx @@ -1,13 +1,13 @@ - + - + # Error 40018: Delta decode failure @@ -26,6 +26,7 @@ The SDK couldn't decode a delta-compressed message, which means the channel need - No immediate action required - Ably SDKs automatically recover - Monitor for repeated occurrences which may indicate network issues +- For .NET users: Ensure IO.Ably.DeltaCodec assembly is installed - Check SDK logs to verify the recovery process completed ## Error Messages @@ -38,6 +39,7 @@ You may see one of these messages: - "previous id '{id}' is incompatible with message delta {delta}" - "Failed to decode data: {specific error}" - "Data is nil" +- "Could not load file or assembly 'IO.Ably.DeltaCodec, Version=1.0.0.0'" (.NET specific) ## Common Causes @@ -45,19 +47,22 @@ You may see one of these messages: - Previous message ID doesn't match expected sequence - Messages received out of order - Missing base message for delta decompression - + - Network interruption causing message gap + 2. **Network data corruption** (25% of cases) - Corrupted delta data during transmission - Invalid VCDIFF format received - Network interruption during message transfer - + - Partial message delivery + 3. **Missing dependencies (.NET specific)** (15% of cases) - IO.Ably.DeltaCodec assembly not found - Assembly version mismatch - Strong-naming requirements not met - + - NuGet package not installed or corrupted + ## Resolution Steps @@ -65,7 +70,8 @@ You may see one of these messages: - The SDK automatically reattaches to the channel - Recovery includes restoring message continuity from the last known point - No code changes required in most cases - + - Recovery typically completes within seconds + 2. **Monitor recovery process** ```javascript @@ -79,46 +85,87 @@ You may see one of these messages: channel.on('attached', () => { console.log('Channel reattached successfully'); }); + + // Check connection state + ably.connection.on('connected', () => { + console.log('Connection restored'); + }); ``` - + 3. **For .NET users experiencing assembly errors** - - Ensure the IO.Ably.DeltaCodec NuGet package is installed + - Install the IO.Ably.DeltaCodec NuGet package: + ```bash + Install-Package IO.Ably.DeltaCodec + ``` - Verify assembly versions match the SDK version - Check that strong-naming requirements are met in your project - + - For .NET Framework projects, ensure the assembly is copied to the output directory + 4. **If errors persist frequently** - - Enable SDK debug logging to capture detailed recovery information - - Check network stability and latency - - Consider temporarily disabling delta compression if the issue continues - + - Enable SDK debug logging to capture detailed recovery information: + ```javascript + const ably = new Ably.Realtime({ + key: 'your-key', + logLevel: 4 // Debug level + }); + ``` + - Check network stability and latency metrics + - Consider temporarily disabling delta compression if the issue continues: + ```javascript + const channel = ably.channels.get('channelName', { + params: { delta: 'false' } + }); + ``` + ## Automatic Handling Ably SDKs automatically handle this error by: 1. Transitioning the channel to ATTACHING state -2. Reattaching with the previous channel serial +2. Reattaching with the previous channel serial (preserving message continuity) 3. Resuming message flow from the correct point 4. No messages are lost during this recovery process -The recovery is transparent to your application and requires no intervention. - +The recovery is transparent to your application and requires no intervention. The SDK manages the entire recovery process internally. + ## Prevention While this error is handled automatically, you can minimize occurrences by: -- Ensuring stable network connectivity -- Keeping SDKs updated to the latest versions +- Ensuring stable network connectivity with consistent latency +- Keeping SDKs updated to the latest versions for improved delta handling - For .NET applications, ensuring all required assemblies are properly deployed - Monitoring for patterns that might indicate systematic issues +- Using connection state recovery features to minimize message gaps + +## Performance Impact + +This error may cause: +- Brief channel reattachment (typically 1-3 seconds) +- Temporary message delay during recovery +- Increased bandwidth usage during recovery (full messages instead of deltas) +- No message loss due to automatic recovery mechanisms ## Related Resources -- [Ably Channels documentation](https://ably.com/docs/channels) -- [Message delta compression](https://ably.com/docs/realtime/channels#delta-compression) +- [Delta compression documentation](https://ably.com/docs/channels/options/deltas) +- [Channel parameters and options](https://ably.com/docs/channels/options) - [Channel state management](https://ably.com/docs/realtime/channels#channel-states) - [Connection state recovery](https://ably.com/docs/realtime/connection#connection-state-recovery) +- [Message delta compression blog post](https://ably.com/blog/message-delta-compression) + +## Related Errors + +• **[40000 - Bad Request](https://help.ably.io/error/40000)** + General request validation failures that may occur alongside delta issues + +• **[80000 - Connection Failed](https://help.ably.io/error/80000)** + Connection failures that can interrupt delta message sequences + +• **[90000 - Channel Operation Failed](https://help.ably.io/error/90000)** + Channel-level failures that may trigger during recovery attempts ## Need Further Help? @@ -132,6 +179,7 @@ When contacting support, please provide: - Steps to reproduce the issue - Any relevant code snippets (without sensitive credentials) - The SDK and version you're using +- For .NET users: Assembly binding logs if experiencing DeltaCodec issues Our team will help you resolve this issue as quickly as possible. @@ -140,40 +188,46 @@ Our team will help you resolve this issue as quickly as possible. + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/40019-missing-plugin.mdx b/src/pages/docs/platform/errors/codes/40019-missing-plugin.mdx index 2adf2a66f4..6521f38e6f 100644 --- a/src/pages/docs/platform/errors/codes/40019-missing-plugin.mdx +++ b/src/pages/docs/platform/errors/codes/40019-missing-plugin.mdx @@ -1,20 +1,21 @@ - + - + # Error 40019: Missing Plugin ## What Happened -The SDK requires a plugin or module that isn't installed or included in your build. +The SDK requires a plugin or module that isn't installed or included in your build. This is part of Ably's modular architecture where advanced features are provided as optional plugins to keep the core SDK size minimal. ## Quick Reference | Error Code | HTTP Status | Category | Retryable | @@ -39,23 +40,25 @@ You may see one of these messages: 1. **VCDiff decoder not installed** (JavaScript/React Native) - Using delta compression without the VCDiff decoder plugin - Receiving messages with 'vcdiff' encoding - - Missing TextEncoder polyfill in React Native - + - Missing TextEncoder polyfill in React Native environments + + 2. **LiveObjects module missing** (Java/Android) - - Attempting to use LiveObjects features + - Attempting to use LiveObjects features without the runtime dependency - Missing runtime dependency in build configuration - + 3. **Experimental plugin not configured** (Go) - Using experimental objects without plugin configuration - Missing ExperimentalObjectsPlugin in client options - + 4. **Modular build missing components** (JavaScript) - Using modular SDK build without required plugins - Optional features not included in custom build - + - Tree-shaking removed necessary components + ## Resolution Steps @@ -74,18 +77,18 @@ You may see one of these messages: plugins: { vcdiff } }); ``` - + 2. **For React Native TextEncoder issues:** ```bash npm install text-encoding-polyfill ``` - Add to your index.js: + Add to your index.js before any Ably imports: ```javascript import 'text-encoding-polyfill'; ``` - + 3. **For modular build plugins:** ```javascript @@ -93,7 +96,7 @@ You may see one of these messages: import { WebSocketTransport, FetchRequest, - // Include other required plugins + // Include other required plugins based on features used } from 'ably/modular/plugins'; const client = new Realtime({ @@ -105,7 +108,7 @@ You may see one of these messages: } }); ``` - + ### Java/Android @@ -128,7 +131,7 @@ Using Maven: runtime ``` - + ### Go @@ -141,7 +144,7 @@ opts := &ably.ClientOptions{ } client, _ := ably.NewRealtime(opts) ``` - + ## Automatic Handling @@ -150,16 +153,22 @@ This error requires manual intervention. SDKs cannot automatically install missi ## Prevention - **Check documentation** for feature-specific plugin requirements before using advanced features -- **Match versions** - Ensure plugin versions match your SDK version +- **Match versions** - Ensure plugin versions match your SDK version exactly - **Minimal builds** - Only include plugins for features you actually use to optimize bundle size - **Test thoroughly** - Verify all required features work in development before deploying - +- **Review build configuration** - Ensure build tools don't accidentally exclude required plugins + ## Related Resources - [Ably SDKs Documentation](https://ably.com/docs/sdks) -- [Delta Compression Guide](https://ably.com/docs/channels#delta-compression) -- [LiveObjects Documentation](https://ably.com/docs/products/liveobjects) -- [Modular JavaScript SDK](https://ably.com/docs/sdks/javascript#modular) +- [Delta Compression Guide](https://ably.com/docs/channels/options/deltas) +- [LiveObjects Documentation](https://ably.com/docs/liveobjects) +- [JavaScript SDK Documentation](https://ably.com/docs/sdk/js/v2.0) + +## Related Errors + +• **[40020 - Browser Incompatibility](https://help.ably.io/error/40020)** + Browser compatibility issues with delta decoding, often seen alongside VCDiff plugin errors ## Need Further Help? @@ -180,44 +189,54 @@ Our team will help you resolve this issue as quickly as possible. - + + + + @@ -226,6 +245,6 @@ To improve this error code documentation: 1. First approach: Update editorial-notes.md in ably-os repository with specific guidance for error 40019 2. Regenerate: Run `./bin/ably-os errors document-error-codes 40019 --force` 3. For broader improvements: Review and update ably-os prompt templates -4. Context: See https://github.com/ably/ably-os/blob/main/docs/ERROR_COMMANDS_GUIDE.md +4. Context: See https://github.com/ably/ably-os/blob/5f4ba43/docs/ERROR_COMMANDS_GUIDE.md 5. Source repository: https://github.com/ably/ably-os --> \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/40020-batch-partial-failure.mdx b/src/pages/docs/platform/errors/codes/40020-batch-partial-failure.mdx index 36178dcf3a..0e71b38976 100644 --- a/src/pages/docs/platform/errors/codes/40020-batch-partial-failure.mdx +++ b/src/pages/docs/platform/errors/codes/40020-batch-partial-failure.mdx @@ -1,13 +1,13 @@ - + - + # Error 40020: Batch operation partial failure @@ -39,32 +39,33 @@ The response will always include a `batchResponse` field containing the detailed ## Common Causes 1. **Mixed validity in batch operations** (70% of cases) - + - Some channels exist while others don't - Some tokens are valid while others are expired - Some messages meet size limits while others exceed them 2. **Permissions issues for specific operations** (20% of cases) - + - Token has permission for some channels but not others - Mixed capability requirements across operations 3. **Resource limits on individual items** (10% of cases) - + - Some messages exceed size limits - Rate limits hit for specific channels ## Resolution Steps 1. **Access the batch response details** - + ```javascript if (response.error && response.error.code === 40020) { // Partial success - check individual results response.batchResponse.forEach((result, index) => { if (result.error) { console.log(`Operation ${index} failed:`, result.error.message); - // Handle specific error + console.log(`Error code: ${result.error.code}`); + // Handle specific error based on code } else { console.log(`Operation ${index} succeeded`); // Process successful result @@ -72,16 +73,16 @@ The response will always include a `batchResponse` field containing the detailed }); } ``` - + 2. **Identify and fix failed operations** - + - Each item in `batchResponse` corresponds to an operation in your original batch - Failed items contain an `error` object with specific error code and message - Use the individual error codes to determine the specific fix needed 3. **Retry only failed operations** - + - Extract failed operations from the batch - Fix the issues based on individual error messages - Create a new batch with only the corrected operations @@ -89,7 +90,7 @@ The response will always include a `batchResponse` field containing the detailed ## Automatic Handling - + Ably SDKs recognize error 40020 as a partial success indicator and will not throw exceptions. Instead, they provide access to the `batchResponse` field for you to handle individual results. The SDK will not automatically retry partial failures—you must handle them based on your application logic. ## Code Examples @@ -114,19 +115,28 @@ try { err.batchResponse.forEach((result, index) => { if (result.error) { console.error(`Channel ${batchPublishData[index].channel} failed:`, result.error.message); - failedOps.push(batchPublishData[index]); + console.error(`Error code: ${result.error.code}`); + + // Collect failed operations for potential retry + if (result.error.code === 40102) { // Token expired + // Need to refresh token + } else if (result.error.code === 40105) { // Permission denied + // Skip this channel or request different permissions + } else { + failedOps.push(batchPublishData[index]); + } } }); // Optionally retry failed operations after fixing issues if (failedOps.length > 0) { - console.log('Retrying failed operations...'); + console.log(`Retrying ${failedOps.length} failed operations...`); // Fix issues and retry } } } ``` - + ### Batch token revocation with partial failures @@ -147,22 +157,71 @@ if (response.error?.code === 40020) { }); } ``` - + + +### Java SDK specific handling + +```java +// Java SDK allows 40020 to pass through without exception +try { + HttpPaginatedResponse response = ably.request(method, path, params, body, headers); + + // Check if this is a partial success + if (response.errorInfo != null && response.errorInfo.code == 40020) { + // Access batch response data + JsonArray batchResponse = response.items(); + for (int i = 0; i < batchResponse.size(); i++) { + JsonObject result = batchResponse.get(i).getAsJsonObject(); + if (result.has("error")) { + // Handle individual error + ErrorInfo error = ErrorInfo.fromJson(result.get("error")); + System.out.println("Operation " + i + " failed: " + error.message); + } + } + } +} catch (AblyException e) { + // Won't be thrown for 40020 - SDK allows it through +} +``` + ## Affected Endpoints - + This error can occur with these batch endpoints: - `POST /messages` - Batch message publishing - `POST /revokeTokens` - Batch token revocation - `GET /presence` - Batch presence retrieval +## SDK-Specific Notes + +### Java SDK + +If you're having trouble accessing the `batchResponse` data in the Java SDK, ensure you're using the latest version or enable verbose logging to see the full response details. + +### JavaScript SDK + +Note: If you see error 40020 with the message about delta decoding and browser compatibility, this is a different issue related to message decoding, not batch operations. + ## Related Resources -- [Batch Publishing Documentation](https://ably.com/docs/rest/messages#batch-publish) -- [API Reference - Batch Operations](https://ably.com/docs/api/rest-api#batch-operations) -- [Error Handling Best Practices](https://ably.com/docs/best-practice/error-handling) -- Related errors: [40140](./40140-token-error.md) (Token errors), [40171](./40171-channel-error.md) (Channel errors) +- [Batch Publishing Documentation](https://ably.com/docs/messages/batch) +- [API Reference - Batch Operations](https://ably.com/docs/api/rest-api) +- [Message Batching](https://ably.com/docs/rest/batch) + +## Related Errors + +• **[40102 - Token Expired](https://help.ably.io/error/40102)** + May occur for individual operations when tokens expire during batch processing + +• **[40105 - Insufficient Permissions](https://help.ably.io/error/40105)** + Common cause of partial failures when token lacks permissions for some channels + +• **[40400 - Resource Not Found](https://help.ably.io/error/40400)** + Can occur when batch includes non-existent channels or invalid resource references + +• **[42910 - Rate Limit Exceeded](https://help.ably.io/error/42910)** + May affect individual channels in a batch when rate limits are hit ## Need Further Help? @@ -176,6 +235,7 @@ When contacting support, please provide: - Steps to reproduce the issue - Any relevant code snippets (without sensitive credentials) - The SDK and version you're using +- The specific batch operations that are failing Our team will help you resolve this issue as quickly as possible. @@ -183,42 +243,47 @@ Our team will help you resolve this issue as quickly as possible. - + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/40022-invalid-resource-or-deprecated-feature.mdx b/src/pages/docs/platform/errors/codes/40022-invalid-resource-or-deprecated-feature.mdx index 5f5f9b3d6f..fa56565c02 100644 --- a/src/pages/docs/platform/errors/codes/40022-invalid-resource-or-deprecated-feature.mdx +++ b/src/pages/docs/platform/errors/codes/40022-invalid-resource-or-deprecated-feature.mdx @@ -1,11 +1,11 @@ - + @@ -33,6 +33,7 @@ Your request failed because you're either trying to use a deprecated feature (AP You may see one of these messages: - "API Streamer is no longer offered, contact support@ably.com for more information" - "Invalid resource" (with specific details in the response) +- "API Streamer has been shut down" - Context-specific validation messages in the `details` field ## Common Causes @@ -41,7 +42,7 @@ You may see one of these messages: - Attempting to attach to channels starting with `[product:` - Using legacy exchange (xchg) channels - Following outdated documentation referencing API Streamer - + ### 2. **Control API Validation Failures** (For app/rule management) - **Rule Configuration Issues**: @@ -55,7 +56,7 @@ You may see one of these messages: - Invalid AWS regions for queues - Malformed certificates - Duplicate resource names - + ## Resolution Steps @@ -64,37 +65,37 @@ You may see one of these messages: 1. **Identify deprecated channel names** - Check if your channel names start with `[product:` - These channels are no longer supported - + 2. **Update your channel naming** - Remove the `[product:` prefix - Use standard Ably channel naming conventions - - See [Channel naming documentation](https://ably.com/docs/channels#name-syntax) + - See [Channel documentation](https://ably.com/docs/channels) 3. **Contact support for migration assistance** - Email support@ably.com with your use case - Include your app ID and current channel patterns - Support team will help with migration to supported features - + ### For Control API Validation Errors 1. **Check the error details** - The response includes a `details` field with specific validation issues - Example: `"queueId": "Could not find queue with id "` - + 2. **Fix rule configuration issues** - For enveloped rules: Use `enveloped=true` with `requestMode=batch` - For non-enveloped rules: Use `enveloped=false` with `requestMode=single` - Some rule types (CloudFlare, IFTTT, Zapier) don't support enveloped parameter - + 3. **Validate resource parameters** - For queue regions: Use valid regions (us-east-1-a, eu-west-1-a) - For resource names: Ensure they're unique within your app - For certificates: Ensure proper formatting - + ## Automatic Handling @@ -108,17 +109,24 @@ This error will not be automatically retried by Ably SDKs as it indicates a conf - Remove any references to exchange or xchg channels from your code ### Avoiding Control API Validation Errors -- Always validate parameters against the [Control API documentation](https://ably.com/docs/api/control-api) +- Always validate parameters against the [Control API documentation](https://ably.com/docs/control-api) - Use the correct enveloped/requestMode combinations for rules - Check resource existence before referencing in rules - Use unique names for all resources ## Related Resources -- [Channel naming conventions](https://ably.com/docs/channels#name-syntax) -- [Control API documentation](https://ably.com/docs/api/control-api) -- [Integration rules documentation](https://ably.com/docs/general/integrations) -- Related errors: [40000](./40000-bad-request.mdx), [40400](./40400-not-found.mdx) +- [Channel documentation](https://ably.com/docs/channels) +- [Control API documentation](https://ably.com/docs/control-api) +- [Integration rules documentation](https://ably.com/docs/integrations/webhooks) + +## Related Errors + +• **[40000 - Bad Request](https://help.ably.io/error/40000)** + General client error for malformed requests or invalid states + +• **[40400 - Not Found](https://help.ably.io/error/40400)** + Resource not found errors that may occur alongside validation failures ## Need Further Help? @@ -140,12 +148,15 @@ Our team will help you resolve this issue as quickly as possible. + + + @@ -180,6 +191,6 @@ To improve this error code documentation: 1. First approach: Update editorial-notes.md in ably-os repository with specific guidance for error 40022 2. Regenerate: Run `./bin/ably-os errors document-error-codes 40022 --force` 3. For broader improvements: Review and update ably-os prompt templates -4. Context: See https://github.com/ably/ably-os/blob/main/docs/ERROR_COMMANDS_GUIDE.md +4. Context: See https://github.com/ably/ably-os/blob/5f4ba43/docs/ERROR_COMMANDS_GUIDE.md 5. Source repository: https://github.com/ably/ably-os --> \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/40023-protocol-version-required.mdx b/src/pages/docs/platform/errors/codes/40023-protocol-version-required.mdx index d90a5f0205..39d729b90d 100644 --- a/src/pages/docs/platform/errors/codes/40023-protocol-version-required.mdx +++ b/src/pages/docs/platform/errors/codes/40023-protocol-version-required.mdx @@ -1,13 +1,13 @@ - + - + # Error 40023: Action requires a newer protocol version @@ -41,18 +41,20 @@ You may see one of these messages: - Your SDK only supports protocol v1 - Attempting to use LiveObjects or message annotations - SDK hasn't been updated in several months + 2. **New feature adoption** (10% of cases) - Trying to implement LiveObjects for collaborative features - Attempting to use message updates or deletes - Adding message annotations to existing implementation + ## Resolution Steps 1. **Check your current SDK version** - Review your package.json, Gemfile, requirements.txt, or equivalent - - Compare with the latest version on [Ably's download page](https://ably.com/download) - + - Compare with the latest version on [Ably's SDKs page](https://ably.com/docs/sdks) + 2. **Update to the latest SDK version** @@ -61,14 +63,14 @@ You may see one of these messages: npm install ably@latest ``` - For other platforms, see the [SDK installation guide](https://ably.com/docs/getting-started/setup) + For other platforms, see the [SDK setup guide](https://ably.com/docs/getting-started/setup) 3. **Verify protocol v2 support** - Latest SDK versions automatically use protocol v2 - No additional configuration required - Features become available immediately after upgrade - + 4. **Test the feature again** - Your application should now support LiveObjects, message annotations, and other v2 features @@ -92,14 +94,24 @@ The following features require protocol version 2: - **Message annotations**: Metadata attached to messages - **Message updates**: Editing published messages - **Message deletes**: Removing published messages - + ## Related Resources -- [Ably SDK downloads](https://ably.com/download) -- [LiveObjects documentation](https://ably.com/docs/products/liveobjects) -- [Protocol version information](https://ably.com/docs/client-lib-development-guide/protocol-versions) -- Related errors: None specific to protocol versioning +- [Ably SDKs](https://ably.com/docs/sdks) +- [LiveObjects documentation](https://ably.com/liveobjects) +- [Protocol specification](https://github.com/ably/specification) + +## Related Errors + +• **[40000 - Bad Request](https://help.ably.io/error/40000)** + General client request errors that may include protocol-related issues + +• **[40101 - Invalid API Key](https://help.ably.io/error/40101)** + Authentication errors that could prevent accessing v2 features + +• **[80013 - Protocol Error](https://help.ably.io/error/80013)** + Protocol violations or version mismatches during connection ## Need Further Help? @@ -120,43 +132,48 @@ Our team will help you resolve this issue as quickly as possible. - - + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/40024-channel-mode-required.mdx b/src/pages/docs/platform/errors/codes/40024-channel-mode-required.mdx index fb46c95437..1eeb88c95a 100644 --- a/src/pages/docs/platform/errors/codes/40024-channel-mode-required.mdx +++ b/src/pages/docs/platform/errors/codes/40024-channel-mode-required.mdx @@ -1,13 +1,13 @@ - + - + # Error 40024: Channel Mode Required for LiveObjects @@ -24,99 +24,157 @@ The channel you're trying to use for LiveObjects operations doesn't have the req ## Quick Fix -- Set the required channel mode (`object_subscribe` or `object_publish`) when creating the channel -- Ensure the channel is configured for LiveObjects before attempting operations -- Check that your channel options include the appropriate mode for your operation +- Set the required channel mode (`OBJECT_SUBSCRIBE` or `OBJECT_PUBLISH`) when creating the channel +- For reading objects: use `OBJECT_SUBSCRIBE` mode +- For writing objects: use `OBJECT_PUBLISH` mode +- For both operations: include both modes in your channel configuration ## Error Messages You may see one of these messages: -- "'{mode}' channel mode must be set for this operation" -- "channel mode must be set for this operation" +- `"{mode}" channel mode must be set for this operation` (JavaScript SDK) +- `"channel mode must be set for this operation"` (Java SDK) -The `{mode}` placeholder will be replaced with the specific mode required for your operation. +The `{mode}` placeholder indicates which specific mode is required: either `OBJECT_SUBSCRIBE` for read operations or `OBJECT_PUBLISH` for write operations. ## Common Causes -1. **Missing channel mode configuration** (90% of cases) +1. **Missing channel mode configuration** (85% of cases) - Channel created without LiveObjects mode options - - Default channel configuration used instead of LiveObjects-specific setup - + - Using default channel configuration instead of LiveObjects-specific setup + - Attempting to use LiveObjects on a standard Pub/Sub channel + 2. **Incorrect mode for operation** (10% of cases) - - Using `object_subscribe` mode for publish operations - - Using `object_publish` mode for subscribe operations + - Trying to read objects with only `OBJECT_PUBLISH` mode + - Trying to write objects with only `OBJECT_SUBSCRIBE` mode + - Missing one of the required modes for bidirectional operations +3. **Plugin not loaded** (5% of cases) + - LiveObjects plugin not included in JavaScript SDK build + - Missing LiveObjects dependency in Java/Kotlin projects + + ## Resolution Steps -1. **Configure the channel with the required mode** - +1. **Configure the channel with the required modes** + For JavaScript/TypeScript: ```javascript - // For subscribe operations - const channel = ably.channels.get('my-channel', { - modes: ['object_subscribe'] + // Import LiveObjects plugin (required for JavaScript SDK) + import * as Ably from 'ably'; + import { LiveObjects } from '@ably/liveobjects'; + + const client = new Ably.Realtime({ + key: 'your-api-key', + plugins: { LiveObjects } }); - // For publish operations - const channel = ably.channels.get('my-channel', { - modes: ['object_publish'] + // For read-only access + const readChannel = client.channels.get('my-channel', { + modes: ['OBJECT_SUBSCRIBE'] }); - // For both operations - const channel = ably.channels.get('my-channel', { - modes: ['object_subscribe', 'object_publish'] + // For write-only access + const writeChannel = client.channels.get('my-channel', { + modes: ['OBJECT_PUBLISH'] + }); + + // For full read/write access (most common) + const channel = client.channels.get('my-channel', { + modes: ['OBJECT_SUBSCRIBE', 'OBJECT_PUBLISH'] }); ``` - + For Java/Kotlin: ```java // Configure channel with required modes ChannelOptions options = new ChannelOptions(); - options.modes = new String[] { "object_subscribe", "object_publish" }; + options.modes = new ChannelMode[] { + ChannelMode.OBJECT_SUBSCRIBE, + ChannelMode.OBJECT_PUBLISH + }; Channel channel = ably.channels.get("my-channel", options); + + // For Kotlin + val options = ChannelOptions().apply { + modes = arrayOf( + ChannelMode.OBJECT_SUBSCRIBE, + ChannelMode.OBJECT_PUBLISH + ) + } + val channel = ably.channels.get("my-channel", options) ``` - + -2. **Verify your LiveObjects operations match the configured mode** - - Use `object_subscribe` mode for receiving object updates - - Use `object_publish` mode for creating or modifying objects - - Use both modes if your application needs full read/write access - +2. **Verify your authentication has the correct capabilities** + ```javascript + // Ensure your token/API key has the required capabilities + const tokenRequest = await ably.auth.createTokenRequest({ + capability: { + 'my-channel': ['object-subscribe', 'object-publish'] + } + }); + ``` + -3. **Check your channel configuration before operations** +3. **Check mode requirements for your specific operation** + - **Reading objects** (get, subscribe): Requires `OBJECT_SUBSCRIBE` + - **Writing objects** (set, create, update): Requires `OBJECT_PUBLISH` + - **Both operations**: Include both modes in the channel configuration + + +4. **Verify the LiveObjects plugin is loaded (JavaScript only)** ```javascript - // Verify channel has required modes - const channel = ably.channels.get('my-channel'); - if (!channel.options?.modes?.includes('object_subscribe')) { - // Reconfigure channel with required mode - channel = ably.channels.get('my-channel', { - modes: ['object_subscribe', 'object_publish'] - }); + // Check if LiveObjects plugin is available + if (!client.plugins?.LiveObjects) { + console.error('LiveObjects plugin not loaded'); + // Add the plugin to your client configuration } ``` - + ## Automatic Handling -This is a configuration error that will not be automatically retried. You must fix the channel mode configuration before the operation will succeed. +This is a configuration error that will not be automatically retried. The SDK will throw this error immediately when you attempt a LiveObjects operation without the proper channel mode. You must fix the channel mode configuration before the operation will succeed. ## Prevention -- Always configure channels with appropriate modes when using LiveObjects -- Set both `object_subscribe` and `object_publish` modes if your application performs both read and write operations -- Consider creating a helper function to ensure consistent channel configuration across your application -- Review the [LiveObjects documentation](https://ably.com/docs/liveobjects) for complete configuration requirements +- **Always configure channels explicitly for LiveObjects**: Don't rely on default channel configuration +- **Use both modes for typical applications**: Most LiveObjects use cases require both read and write access +- **Create a helper function** for consistent channel configuration: + ```javascript + function getLiveObjectsChannel(channelName, readonly = false) { + const modes = readonly + ? ['OBJECT_SUBSCRIBE'] + : ['OBJECT_SUBSCRIBE', 'OBJECT_PUBLISH']; + + return client.channels.get(channelName, { modes }); + } + ``` + +- **Check capabilities in your authentication**: Ensure your API key or token includes the necessary LiveObjects capabilities ## Related Resources - [LiveObjects documentation](https://ably.com/docs/liveobjects) -- [Channel configuration guide](https://ably.com/docs/channels) -- [LiveObjects API reference](https://ably.com/docs/api/realtime-sdk/channels#channel-options) -- Related errors: [40019](./40019-missing-plugin.md) (missing LiveObjects dependency) +- [LiveObjects quickstart guide](https://ably.com/docs/liveobjects/quickstart) +- [Channel configuration guide](https://ably.com/docs/api/realtime-sdk/channels) +- [Authentication capabilities](https://ably.com/docs/auth/capabilities) + +## Related Errors + +• **[40019 - Missing Plugin](https://help.ably.io/error/40019)** + LiveObjects plugin not included in JavaScript SDK build + +• **[40100 - Access Refused](https://help.ably.io/error/40100)** + Authentication lacks required LiveObjects capabilities + +• **[40101 - Invalid API Key](https://help.ably.io/error/40101)** + API key configuration issues that may affect LiveObjects access ## Need Further Help? @@ -137,31 +195,46 @@ Our team will help you resolve this issue as quickly as possible. - + + + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/40030-invalid-publish-request.mdx b/src/pages/docs/platform/errors/codes/40030-invalid-publish-request.mdx index 4555558c09..25a36169c4 100644 --- a/src/pages/docs/platform/errors/codes/40030-invalid-publish-request.mdx +++ b/src/pages/docs/platform/errors/codes/40030-invalid-publish-request.mdx @@ -1,11 +1,11 @@ - + @@ -37,21 +37,21 @@ You'll see one of these messages: ## Common Causes 1. **Invalid extras field format** (90% of cases) - + - Sending `extras` as a string instead of an object - Using JSON.stringify on the extras value - Sending `extras` as a number, boolean, or array - Form-encoded requests with incorrectly structured extras 2. **Malformed message structure** (10% of cases) - + - General publish request validation failure - Invalid parameter combinations ## Resolution Steps 1. **If the error mentions "extras must be an object"** - + Check your publish code - the `extras` field must be a plain JavaScript object: @@ -72,10 +72,10 @@ You'll see one of these messages: extras: { ref: 'some-ref' } // Plain object }); ``` - + 2. **For REST API requests with form encoding** - + When using `Content-Type: application/x-www-form-urlencoded`, structure your data properly. The `extras` field cannot be sent as a simple form field - use JSON content type instead: @@ -87,7 +87,7 @@ You'll see one of these messages: ``` 3. **Review your publish request structure** - + Ensure your message follows the correct format: - `name`: (optional) Event name as a string @@ -96,7 +96,7 @@ You'll see one of these messages: - `id`: (optional) Unique message ID for idempotency 4. **Check the full error message** - + Error 40030 often includes specific details beyond the generic message. Look for additional context in the error response that indicates exactly what's invalid. @@ -114,8 +114,15 @@ This is a client error that indicates a problem with your request format. Ably S ## Related Resources - [Publishing messages documentation](https://ably.com/docs/channels#publish) -- [Message structure reference](https://ably.com/docs/api/rest-sdk#message) -- Related errors: [40009](https://ably.com/docs/platform/errors/codes/40009) (message too large), [40032](https://ably.com/docs/platform/errors/codes/40032) (impermissible extras field) +- [Message structure reference](https://ably.com/docs/channels/messages) + +## Related Errors + +• **[40009 - Maximum message length exceeded](https://faqs.ably.com/error-code-40009-maximum-message-length-exceeded)** + Occurs when message size exceeds your package limits + +• **[40032 - Invalid publish request (impermissible extras field)](https://faqs.ably.com/error-code-40032-invalid-publish-request-impermissible-extras-field)** + Related validation error when extras contains disallowed properties ## Need Further Help? @@ -136,39 +143,42 @@ Our team will help you resolve this issue as quickly as possible. - + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/40031-invalid-message-id.mdx b/src/pages/docs/platform/errors/codes/40031-invalid-message-id.mdx index bd77845dc8..480de10ffe 100644 --- a/src/pages/docs/platform/errors/codes/40031-invalid-message-id.mdx +++ b/src/pages/docs/platform/errors/codes/40031-invalid-message-id.mdx @@ -1,11 +1,11 @@ - + @@ -41,17 +41,17 @@ You may see one of these messages: 1. **Mixed ID specification** (60% of cases) - Some messages in a batch have IDs while others don't - All messages must have IDs or none should have IDs - + 2. **Incorrect multi-message format** (30% of cases) - When publishing multiple messages with IDs, they must follow: `baseMsgId:0`, `baseMsgId:1`, etc. - Sequential indexing starting at 0 is required - + 3. **Invalid ID type** (10% of cases) - Message IDs must be strings - Numbers or other types are not accepted - + ## Resolution Steps @@ -66,7 +66,7 @@ You may see one of these messages: // ❌ Wrong: Non-string ID channel.publish({ name: 'event', data: payload, id: 12345 }); ``` - + 2. **For multi-message publishing: Follow the required format** ```javascript @@ -94,13 +94,13 @@ You may see one of these messages: { name: 'event2', data: 'data2' } ]); ``` - + 3. **Verify your implementation** - Check that all IDs are strings - Ensure consistent ID usage across all messages - For batches, verify the sequential index pattern - + ## Automatic Handling @@ -128,7 +128,7 @@ const messages = orders.map((order, index) => ({ })); await channel.publish(messages); ``` - + ## Prevention @@ -140,9 +140,20 @@ await channel.publish(messages); ## Related Resources -- [Idempotent message publishing](https://ably.com/docs/realtime/messages#idempotency) -- [Message batching](https://ably.com/docs/rest/messages#batch) -- [Publishing messages](https://ably.com/docs/realtime/messages#publish) +- [Idempotent message publishing](https://ably.com/docs/channels/messages#idempotent-publishing) +- [Message batching](https://ably.com/docs/channels/messages#batch-publishing) +- [Publishing messages](https://ably.com/docs/channels/messages#publish) + +## Related Errors + +• **[40000 - Bad Request](https://help.ably.io/error/40000)** + General bad request error that may occur with other message publishing issues + +• **[40012 - Invalid Client ID](https://help.ably.io/error/40012)** + Related error when the client ID in messages doesn't match authentication + +• **[40103 - Invalid Use of Basic Auth](https://help.ably.io/error/40103)** + Authentication issues that can affect message publishing capabilities ## Need Further Help? @@ -163,40 +174,43 @@ Our team will help you resolve this issue as quickly as possible. - + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/40032-invalid-extras-field.mdx b/src/pages/docs/platform/errors/codes/40032-invalid-extras-field.mdx index 088b8e4bb9..e7b0b714c8 100644 --- a/src/pages/docs/platform/errors/codes/40032-invalid-extras-field.mdx +++ b/src/pages/docs/platform/errors/codes/40032-invalid-extras-field.mdx @@ -1,13 +1,13 @@ - + - + # Error 40032: Invalid extras field @@ -44,24 +44,24 @@ You may see one of these messages: 1. **Adding custom fields directly to extras** (60% of cases) - Putting arbitrary data in the extras object - Using fields that are reserved for Ably functionality - + 2. **Incorrect headers structure** (25% of cases) - Using nested objects or arrays in headers - Using non-primitive types as header values - + 3. **Ephemeral flag on wrong message types** (15% of cases) - Setting `ephemeral: true` on presence messages - Setting `ephemeral: true` on state messages - + ## Resolution Steps 1. **Review your extras field structure** - The `extras` field is reserved for Ably-specific functionality - Only certain fields are allowed in extras - + 2. **Move custom data to headers** ```javascript @@ -87,7 +87,7 @@ You may see one of these messages: } }); ``` - + 3. **Ensure headers are flat key-value pairs** ```javascript @@ -108,7 +108,7 @@ You may see one of these messages: } } ``` - + 4. **Remove ephemeral flag from presence/state messages** ```javascript @@ -122,12 +122,12 @@ You may see one of these messages: // No ephemeral flag for presence messages }); ``` - + 5. **For Integrations: Use ASCII header names** - When using Integrations (formerly Reactor), ensure header names use only ASCII characters - Headers will be converted to HTTP, AMQP, or other protocol headers - + ## Automatic Handling @@ -140,14 +140,25 @@ This is a client error that will not be automatically retried. You must fix the - **Keep headers flat**: Ensure headers contain only primitive values (string, number, boolean, null) - **Message type awareness**: Remember that presence and state messages cannot be ephemeral - **ASCII header names**: Use only ASCII characters in header names when using Integrations - + ## Related Resources -- [Message extras documentation](https://ably.com/docs/api/realtime-sdk/messages#extras) -- [Publishing messages](https://ably.com/docs/channels#publish) -- [Presence documentation](https://ably.com/docs/presence) -- Related errors: [40000](./40000-bad-request.md) (General bad request) +- [Message extras documentation](https://ably.com/docs/api/rest-sdk/messages) +- [Publishing messages](https://ably.com/docs/messages/) +- [Presence documentation](https://ably.com/docs/channels) +- [Error code FAQ](https://faqs.ably.com/error-code-40032-invalid-publish-request-impermissible-extras-field) + +## Related Errors + +• **[40000 - Bad Request](https://help.ably.io/error/40000)** + General bad request error that may occur for various invalid message formats + +• **[40010 - Invalid message data](https://help.ably.io/error/40010)** + Related error when message data itself is malformed or exceeds size limits + +• **[40013 - Invalid client ID in message](https://help.ably.io/error/40013)** + Occurs when client ID in message doesn't match authenticated client ## Need Further Help? @@ -168,15 +179,18 @@ Our team will help you resolve this issue as quickly as possible. - + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/40099-internal-testing-error.mdx b/src/pages/docs/platform/errors/codes/40099-internal-testing-error.mdx index 2a4579852e..d16c477509 100644 --- a/src/pages/docs/platform/errors/codes/40099-internal-testing-error.mdx +++ b/src/pages/docs/platform/errors/codes/40099-internal-testing-error.mdx @@ -1,20 +1,20 @@ - + - + # Error 40099: Internal Testing Error ## What Happened -The system encountered an internal testing or development error that should not occur during normal operations. +The system encountered a testing-related error or failed to process message metadata correctly. ## Quick Reference @@ -26,7 +26,7 @@ The system encountered an internal testing or development error that should not - Remove any `_forceNack` parameters from your requests - Check if you're using undocumented testing parameters -- Review your message metadata structure if using advanced features +- Verify message structure if using advanced message features ## Error Messages @@ -39,78 +39,112 @@ You may see one of these messages: 1. **Testing parameter in production** (Most common) - Using `_forceNack=true` parameter in requests - This is an internal testing parameter not intended for production use - + 2. **Message metadata processing failure** (Rare) - Internal failure when adding user claims to message extras - - Related to advanced message features - + - Related to privileged message handling features + + +3. **SDK test expectations** (Development only) + - Expected error when running SDK integration tests + - Part of test validation for error handling paths + ## Resolution Steps 1. **Check for testing parameters** - Review your publish requests for any `_forceNack` parameter - Remove this parameter as it's intended for internal testing only - + - This parameter forces message rejection for testing purposes + 2. **Review message structure** - If you're using advanced message features, verify your message structure - Ensure message extras and metadata are properly formatted - + - Check that any protobuf structures are valid + 3. **For SDK testing** - If you're intentionally testing error handling, this error is expected - - The `_forceNack` parameter deliberately triggers this error for testing purposes - + - The `_forceNack` parameter deliberately triggers this error + - Used to validate SDK error propagation and handling + ## Automatic Handling This error is not automatically retried by Ably SDKs as it indicates either: -- Intentional testing behavior +- Intentional testing behavior via the `_forceNack` parameter - A structural issue with the request that requires correction +- Message metadata processing failure that needs investigation + +## Prevention + +- Never use undocumented parameters like `_forceNack` in production code +- Ensure message structures conform to Ably's documented format +- Keep testing code separate from production implementations ## Related Resources -- [Ably Pub/Sub Documentation](https://ably.com/docs/pubsub) -- [Message Structure Documentation](https://ably.com/docs/channels/messages) +- [Ably Channels Documentation](https://ably.com/docs/channels) +- [Message Structure Documentation](https://ably.com/docs/channels#messages) + +## Related Errors + +• **[40000 - Bad Request](https://faqs.ably.com/error-code-40000-bad-request)** + General bad request error that may occur instead of 40099 in some SDK versions + +• **[40012 - Invalid Client ID](https://faqs.ably.com/error-code-40012-invalid-client-id)** + Related to client identity issues that might affect user claims processing ## Need Further Help? -This error code has limited documentation as it's primarily used for internal testing. If you encounter this error during normal operations, please contact Ably support at https://ably.com/support with: +If you're still experiencing issues after trying these steps, our support team is here to help. + +**Contact Ably Support**: https://ably.com/support + +When contacting support, please provide: - Your account ID and app ID - The full error message including error code 40099 -- The exact request that triggered the error -- Any parameters you're using in your publish requests +- Steps to reproduce the issue +- Any relevant code snippets (without sensitive credentials) +- The SDK and version you're using -Our support team will help you resolve this issue as quickly as possible. +Our team will help you resolve this issue as quickly as possible. + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/40100-unauthorized-access.mdx b/src/pages/docs/platform/errors/codes/40100-unauthorized-access.mdx index e258bc906e..92eef3dabb 100644 --- a/src/pages/docs/platform/errors/codes/40100-unauthorized-access.mdx +++ b/src/pages/docs/platform/errors/codes/40100-unauthorized-access.mdx @@ -1,20 +1,20 @@ - + - + # Error 40100: Unauthorized access ## What Happened -An action cannot be performed due to a lack of authorization. This is distinct from invalid credentials (40101) or other authentication errors. +An action cannot be performed due to a lack of authorization. This is distinct from invalid credentials (40101) or other authentication errors - the credentials may be valid but lack the necessary permissions for the requested operation. ## Quick Reference @@ -26,7 +26,8 @@ An action cannot be performed due to a lack of authorization. This is distinct f - Verify your API key has the necessary capabilities for the operation - Check device credentials match the expected values for push operations -- Ensure you're not attempting to modify immutable properties +- Ensure you're not attempting to modify immutable properties (device ID, app ID) +- For environment switching issues, deactivate push before changing environments ## Error Messages @@ -42,6 +43,7 @@ You may see one of these messages: - "push not enabled for this channel" - "Invalid API key. Ensure you have a valid key configured." - "Failed to get a token" +- "Operation requires admin update rights" ## Common Causes @@ -49,79 +51,102 @@ You may see one of these messages: - Token deviceId doesn't match the requested device operation - Environment switching (staging to production) with existing device credentials - Device credentials persisting across environment changes - + - Particularly common with Bank Jago pattern: multi-environment applications + 2. **Attempting to modify immutable properties** (20% of cases) - - Trying to update device ID or app ID + - Trying to update device ID or app ID after creation - Non-admin users attempting to update transport type - - These properties cannot be changed after creation - + - These properties cannot be changed once set + 3. **Device authentication failures** (15% of cases) - Incompatible deviceSecret or updateToken - Device not found in the system - Credential validation failures - + - Server time synchronization issues + -4. **Push notification issues** (5% of cases) +4. **Push notification configuration issues** (5% of cases) - Push not enabled for the requested channel - Insufficient permissions for push operations - + - Missing admin rights for namespace operations + ## Resolution Steps 1. **For device token mismatches** - Always deactivate push notifications before switching environments - - - If deactivation fails with 40100, consider device reset - - Ensure device credentials are properly cleared when switching between staging and production - - Implement a device re-registration flow when encountering this error - + + - If deactivation fails with 40100, implement a device reset flow + - Clear device credentials completely when switching between staging and production + - Store environment information locally to track which Ably app the device is registered with + - Implement a re-registration flow when encountering this error + 2. **For immutable property errors** - - Device ID and app ID cannot be updated after creation - - Create a new device registration instead of updating these fields - - Transport type updates require admin privileges - + - Device ID and app ID cannot be updated after creation - this is by design + - Create a new device registration instead of attempting to update these fields + - Only admin users can update transport type + - Review your update request to ensure you're not including id or appId fields + 3. **For device authentication issues** - - Verify the deviceSecret or updateToken matches the stored values - - Check that the device exists in your Ably app - - Ensure you're using credentials from the correct environment - + - Verify the deviceSecret or updateToken matches the stored values exactly + - Check that the device exists in your current Ably app (not a different environment) + - Ensure you're using credentials from the correct environment (staging vs production) + - For CLI users, run `ably login` to re-authenticate + 4. **For push notification problems** - Verify push is enabled for the channel in your app settings - - Check your API key has the necessary push capabilities + - Check your API key has the necessary push capabilities configured + - For namespace operations, ensure you have admin update rights - Review the [push notifications documentation](https://ably.com/docs/push) - + -5. **For API key issues** +5. **For API key authorization issues** - Verify your API key is valid and not revoked - Check the key has the necessary capabilities for your operation - - For CLI users, run `ably login` to re-authenticate - + - Review key capabilities in your Ably dashboard under the API Keys tab + - Consider using token authentication for fine-grained access control + ## Automatic Handling -This is an authorization error that will not be automatically retried. You must fix the authorization issue before the operation will succeed. SDKs may suggest re-authentication or provide specific error recovery mechanisms. +This is an authorization error that will not be automatically retried. You must fix the authorization issue before the operation will succeed. SDKs may suggest re-authentication or provide specific error recovery mechanisms, but will not retry the failed operation automatically. ## Prevention -- Store device registration state locally to track environment -- Implement device deactivation before environment switches -- Validate deviceId consistency across token lifecycle -- Ensure token claims match device operations -- Implement proper token refresh mechanisms - +- **Device Management**: Store device registration state locally to track environment +- **Environment Switching**: Always deactivate push before switching between staging and production +- **Token Consistency**: Validate deviceId consistency across token lifecycle +- **Credential Management**: Ensure token claims match device operations exactly +- **Error Recovery**: Implement proper token refresh mechanisms and re-registration flows +- **API Key Security**: Use token authentication on client-side, basic auth only on server-side + + +## Related Errors + +• **[40101 - Invalid Credentials](https://help.ably.io/error/40101)** + Occurs when API key or token format is invalid or has MAC mismatch + +• **[40102 - Token Expired](https://help.ably.io/error/40102)** + Token has expired and needs renewal, distinct from authorization issues + +• **[40103 - Basic Auth Over Non-TLS](https://help.ably.io/error/40103)** + Basic authentication attempted over insecure connection + +• **[40104 - Timestamp Not Current](https://help.ably.io/error/40104)** + Token timestamp is outside acceptable window ## Related Resources - [Authentication documentation](https://ably.com/docs/auth) - [Push notifications guide](https://ably.com/docs/push) -- [Device registration](https://ably.com/docs/push/activate) -- Related errors: [40101](https://help.ably.io/error/40101), [40102](https://help.ably.io/error/40102), [40103](https://help.ably.io/error/40103) +- [Device registration and activation](https://ably.com/docs/push/configure/device) +- [Push Admin API reference](https://ably.com/docs/api/rest-sdk/push-admin) ## Need Further Help? @@ -138,43 +163,57 @@ When contacting support, please provide: Our team will help you resolve this issue as quickly as possible. + + + - + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/40101-invalid-credentials.mdx b/src/pages/docs/platform/errors/codes/40101-invalid-credentials.mdx index 06b32e1355..bbc6d2c387 100644 --- a/src/pages/docs/platform/errors/codes/40101-invalid-credentials.mdx +++ b/src/pages/docs/platform/errors/codes/40101-invalid-credentials.mdx @@ -1,13 +1,13 @@ - + - + # Error 40101: Invalid credentials @@ -41,42 +41,49 @@ You may see one of these messages: - "Unable to set different clientId from that given in options" - "Unable to handle request no application id found in request" - "No key specified: no means to generate a token" +- "Missing key" +- "Invalid token while decoding legacy token format" +- "Invalid token while verifying token signature" +- "Malformed auth credentials while decoding authentication parameters" ## Common Causes 1. **Incorrect API key format** (70% of cases) - + - Missing characters or typos in the API key - Key doesn't follow format: `[AppId].[keyId]:[keySecret]` - Empty or whitespace-only key string - Copy-paste errors with leading/trailing spaces - Incomplete key from environment variables + - Key not splitting into exactly 2 parts at the colon 2. **Token MAC verification failures** (15% of cases) - + - Token request JSON modified after MAC generation - Incorrect key used for token generation vs verification - Token tampering or corruption during transmission - Legacy token format validation failures + - MAC comparison fails during token verification 3. **ClientId mismatches** (10% of cases) - + - Different clientId between token and client constructor - Attempting to change clientId on existing connection - Empty or wildcard clientId when binding is required - JWT missing x-ably-clientId header 4. **Browser or network issues** (5% of cases) - + - Browser extensions stripping Authorization headers (Chrome/Edge) - Corporate proxies removing authentication - - Network timeouts during authentication + - Network timeouts during authentication (especially in APAC region) - Frontdoor vs frontend routing inconsistencies + - High latency causing authentication timeouts ## Resolution Steps 1. **Verify your API key format** - + - Log into your [Ably dashboard](https://ably.com/dashboard) - Navigate to your app → "API Keys" tab - Copy the complete key including all three parts: @@ -85,37 +92,42 @@ You may see one of these messages: - Key Secret (e.g., `U6RN3LJvZzV3DXJk`) - Full format example: `xVLyHw.rPSJgQ:U6RN3LJvZzV3DXJk` - Ensure no spaces before or after the key + - Verify the key contains exactly one period (.) and one colon (:) 2. **Check your implementation** - + - Verify environment variables are loading correctly - Ensure the key contains exactly one period (.) and one colon (:) - Check that your key isn't being truncated or modified - Enable debug logging to see the actual key being used + - Confirm the key splits into exactly 2 parts when split at the colon 3. **For token authentication issues** - + - Ensure the token request JSON hasn't been modified after MAC generation - Verify the same API key is used for both token generation and verification - Check that clientId in token matches clientId in client options - For JWT, confirm clientId is set in the x-ably-clientId header - Generate a fresh token to rule out expiration issues + - Ensure MAC is generated AFTER all other token request fields are set 4. **Debug authentication problems** - + - Enable debug logging in your SDK to see detailed authentication flow - Check for browser extensions that might strip Authorization headers (Chrome/Edge) - Test with a different browser or incognito mode - Verify corporate proxies aren't interfering with authentication - Test with a fresh API key to rule out key-specific issues - Try forcing backend routing with `_forceHandleBy=frontend` parameter if intermittent + - For APAC region users, check if high latency is causing timeouts 5. **For clientId issues** - + - Ensure clientId is consistent across token generation and client initialization - Don't attempt to change clientId on an existing connection - Avoid using empty strings or wildcards ('*') for clientId when binding - Review [Client ID documentation](https://ably.com/docs/auth/identified-clients) + - Note that empty or wildcard clientIds are rejected for security reasons ## Automatic Handling @@ -124,7 +136,7 @@ This is a client error that will not be automatically retried. You must fix the ## Code Examples ### Correct API Key Format - + ```javascript // ✅ Correct: Complete API key with all three parts const ably = new Ably.Realtime('xVLyHw.rPSJgQ:U6RN3LJvZzV3DXJk'); @@ -138,12 +150,15 @@ const ably = new Ably.Realtime('xVLyHw.rPSJgQ'); // ❌ Wrong: Incomplete key with typo const ably = new Ably.Realtime('xVLyHw.rPSJ:U6RN3LJvZzV3DXJk'); +// ❌ Wrong: Empty or whitespace-only key +const ably = new Ably.Realtime(''); + // ✅ Correct: From environment variable (ensure it's loaded) const ably = new Ably.Realtime(process.env.ABLY_API_KEY); ``` ### ClientId Configuration - + ```javascript // ✅ Correct: Consistent clientId const tokenParams = { clientId: 'user123' }; @@ -165,10 +180,13 @@ const client = new Ably.Realtime({ token: token, clientId: '' // Cannot be empty when binding }); + +// ❌ Wrong: Attempting to change clientId +// This will fail with "Unable to set different clientId from that given in options" ``` ### Token Request Validation - + ```javascript // ✅ Correct: Valid token request structure const tokenRequest = { @@ -177,12 +195,13 @@ const tokenRequest = { ttl: 43200000, timestamp: Date.now(), capability: JSON.stringify({"*":["*"]}), - nonce: generateNonce(), - mac: generateMac() // Must be generated AFTER all other fields are set + nonce: generateNonce() }; +// MAC must be generated AFTER all other fields are set +tokenRequest.mac = generateMac(tokenRequest); // ❌ Wrong: Modifying after MAC generation -tokenRequest.mac = generateMac(); +tokenRequest.mac = generateMac(tokenRequest); tokenRequest.clientId = "bar"; // This invalidates the MAC ``` @@ -194,6 +213,8 @@ tokenRequest.clientId = "bar"; // This invalidates the MAC - Test authentication in development before deploying - Monitor authentication error rates to detect issues early - Use debug logging during development to catch authentication problems +- For enterprise deployments, test with corporate proxy configurations +- In high-latency regions (APAC), implement appropriate timeout handling ## Performance Impact @@ -205,6 +226,17 @@ Authentication failures prevent all Ably operations: The error does not trigger automatic retries, preventing unnecessary load on the authentication system. +## Related Errors + +• **[40102 - Token expired](https://help.ably.io/error/40102)** + Token has exceeded its TTL and needs renewal + +• **[40400 - Not found](https://help.ably.io/error/40400)** + Related error when app ID or key ID portions are invalid + +• **[40005 - Invalid credential](https://help.ably.io/error/40005)** + Similar authentication error with different validation context + ## Related Resources - [Authentication documentation](https://ably.com/docs/auth) @@ -212,7 +244,6 @@ The error does not trigger automatic retries, preventing unnecessary load on the - [Token authentication guide](https://ably.com/docs/auth/token) - [Client ID explained](https://ably.com/docs/auth/identified-clients) - [Debug logging guide](https://ably.com/docs/realtime/connection#connection-state-recovery) -- Related errors: [40102 - Token expired](https://help.ably.io/error/40102), [40400 - Not found](https://help.ably.io/error/40400) ## Need Further Help? @@ -228,6 +259,7 @@ When contacting support, please provide: - The SDK and version you're using - Whether the error is intermittent or consistent - Browser and version (for web applications) +- Your region (especially if in APAC where latency issues are more common) Our team will help you resolve this issue as quickly as possible. @@ -236,35 +268,35 @@ Our team will help you resolve this issue as quickly as possible. + + + @@ -309,6 +348,6 @@ To improve this error code documentation: 1. First approach: Update editorial-notes.md in ably-os repository with specific guidance for error 40101 2. Regenerate: Run `./bin/ably-os errors document-error-codes 40101 --force` 3. For broader improvements: Review and update ably-os prompt templates -4. Context: See https://github.com/ably/ably-os/blob/main/docs/ERROR_COMMANDS_GUIDE.md +4. Context: See https://github.com/ably/ably-os/blob/5f4ba43/docs/ERROR_COMMANDS_GUIDE.md 5. Source repository: https://github.com/ably/ably-os --> \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/40102-incompatible-credentials.mdx b/src/pages/docs/platform/errors/codes/40102-incompatible-credentials.mdx index 341b24af60..f8034d1e26 100644 --- a/src/pages/docs/platform/errors/codes/40102-incompatible-credentials.mdx +++ b/src/pages/docs/platform/errors/codes/40102-incompatible-credentials.mdx @@ -1,13 +1,13 @@ - + - + # Error 40102: Incompatible credentials @@ -27,6 +27,7 @@ Your authentication credentials contain mismatched or incompatible information t - Ensure your client ID remains consistent across tokens and connections - Use the same API key throughout your authentication flow - For user login scenarios, disconnect and reconnect with new credentials +- Check for spaces or special characters in your client ID that might cause mismatches ## Error Messages @@ -37,6 +38,8 @@ You may see one of these messages: - "Incompatible keys specified" - "Client ID is immutable once configured for a client. Client ID cannot be changed to '{new_client_id}'" - "Unexpected clientId mismatch: client has {current}, requested {requested}" +- "incompatible credentials" +- "wildcard client ID" (when using '*' with credentials) ## Common Causes @@ -44,22 +47,25 @@ You may see one of these messages: - User transitions from anonymous to authenticated state - JWT token contains different client ID than current connection - User switches accounts while maintaining same connection - + - Space character differences in client ID (e.g., "Jon1-..." vs "Jon 1-...") + 2. **Different API keys in authentication flow** (20% of cases) - Attempting to authorize with different API key than originally configured - Mixing API keys between token generation and client initialization - + - Key name mismatch in token request when using different keys + 3. **Attempting to change immutable client ID** (15% of cases) - Trying to update client ID after it's been set - Client ID cannot be changed once configured (unless original was wildcard '*') - + 4. **Token client ID conflicts** (5% of cases) - Token contains client ID that doesn't match configured client ID - Using wildcard '*' client ID inappropriately with credentials - + - Token validation fails during setTokenDetails operation + ## Resolution Steps @@ -67,41 +73,56 @@ You may see one of these messages: - Check that all tokens use the same client ID - Ensure your authentication callback returns consistent client IDs - Review token generation to confirm correct client ID assignment - + - Look for spaces or special characters that might differ between client IDs + 2. **For user authentication transitions** - Disconnect the current connection when user logs in/out - Create a new connection with updated credentials - Reattach to channels after reconnecting - + - Consider implementing automatic recovery like Laravel Echo does + 3. **Check API key usage** - Use a single API key throughout your application - Don't mix different API keys in authorize() calls - Verify key consistency between server and client components - + - Ensure token request keyName matches the API key being used + 4. **Handle client ID immutability** - Never attempt to change client ID after initialization - If client ID must change, create a new connection - Use wildcard '*' client ID only when appropriate for your use case - + - Remember that wildcard client ID cannot be used with basic auth credentials + -5. **Validate token contents** +5. **Validate token contents before use** ```javascript // Check token details before use const tokenDetails = await ably.auth.requestToken(); console.log('Token clientId:', tokenDetails.clientId); console.log('Current clientId:', ably.auth.clientId); + + // Ensure they match or handle mismatch appropriately + if (tokenDetails.clientId !== ably.auth.clientId) { + // Reconnect with new credentials + ably.close(); + // Create new connection with matching client ID + } ``` - + ## Automatic Handling This is a client error that will not be automatically retried by Ably SDKs. You must fix the credential mismatch before the operation will succeed. -**Note**: Laravel Echo implements automatic recovery for this error by detecting client ID mismatches and reconnecting with correct credentials. - +**Note**: Laravel Echo implements automatic recovery for this error by: +- Detecting client ID mismatches when connection fails with code 40102 +- Calling `onClientIdChanged()` callback automatically +- Reconnecting the client with correct credentials +- Reattaching all active channels seamlessly + ## Code Examples @@ -115,7 +136,7 @@ const client = new Ably.Realtime({ } }); ``` - + ### Incorrect: Mixing different API keys ```javascript @@ -127,9 +148,9 @@ auth.authorize({ // ✅ Correct: Use same key or token-based auth auth.authorize(); // Uses original configuration ``` - + -### Handle user login transitions +### Handle user login transitions properly ```javascript // When user logs in with new credentials async function handleUserLogin(newUserId) { @@ -144,12 +165,33 @@ async function handleUserLogin(newUserId) { } }); - // 3. Reattach to channels + // 3. Wait for connection + await new Promise((resolve) => { + newClient.connection.on('connected', resolve); + }); + + // 4. Reattach to channels const channel = newClient.channels.get('updates'); await channel.attach(); + + return newClient; } ``` - + + +### Laravel Echo automatic recovery pattern +```javascript +// Laravel Echo handles this automatically +// This shows the internal pattern it uses +connection.on('failed', (stateChange) => { + if (stateChange.reason?.code === 40102) { + // Automatic recovery triggered + onClientIdChanged(); + // Reconnects and reattaches all channels + } +}); +``` + ## Prevention @@ -158,15 +200,36 @@ async function handleUserLogin(newUserId) { - Use a single API key per environment (development, staging, production) - Test authentication flows thoroughly, including user state transitions - Consider using token authentication instead of basic auth for better flexibility - +- Be careful with spaces and special characters in client IDs +- Validate token contents before attempting to use them +- Implement automatic recovery patterns where appropriate + + +## SDK-Specific Behavior + +Different Ably SDKs handle this error with variations: +- **HTTP Status**: Most use 401, but ably-js uses 403 for token mismatches (to trigger RSA15c permanent failure), ably-python uses 400 for immutability violations +- **Error Messages**: Some SDKs provide detailed messages with actual vs expected values, others use generic "incompatible credentials" +- **Recovery**: Laravel Echo automatically recovers, other SDKs require manual handling + ## Related Resources - [Authentication documentation](https://ably.com/docs/auth) -- [Client ID explained](https://ably.com/docs/auth/identified-clients) +- [Identified clients](https://ably.com/docs/auth/identified-clients) - [Token authentication](https://ably.com/docs/auth/token) -- [Connection states](https://ably.com/docs/realtime/connection#connection-states) -- Related errors: [40101](./40101-invalid-api-key.md), [40103](./40103-invalid-use-of-basic-auth.md) +- [Connection states](https://ably.com/docs/core-features/authentication) + +## Related Errors + +• **[40101 - Invalid API Key](https://help.ably.io/error/40101)** + Authentication failure due to invalid or missing API key + +• **[40103 - Invalid Use of Basic Auth](https://help.ably.io/error/40103)** + Basic authentication used over non-TLS connection + +• **[40140-40149 - Token Expiration Range](https://help.ably.io/error/40140)** + Various token expiration scenarios that may occur alongside credential mismatches ## Need Further Help? @@ -187,44 +250,55 @@ Our team will help you resolve this issue as quickly as possible. - + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/40103-basic-auth-requires-tls.mdx b/src/pages/docs/platform/errors/codes/40103-basic-auth-requires-tls.mdx index 91d80b90ad..f5f9f63940 100644 --- a/src/pages/docs/platform/errors/codes/40103-basic-auth-requires-tls.mdx +++ b/src/pages/docs/platform/errors/codes/40103-basic-auth-requires-tls.mdx @@ -1,13 +1,13 @@ - + - + # Error 40103: Basic authentication requires TLS @@ -39,55 +39,97 @@ You may see one of these messages: ## Common Causes 1. **TLS disabled in configuration** (80% of cases) - + - Setting `tls: false` in client options - Using HTTP instead of HTTPS endpoints - Development environments with insecure defaults 2. **Network restrictions** (15% of cases) - - - Corporate firewall blocking HTTPS/WSS + + - Corporate firewall blocking HTTPS/WSS ports - Proxy configurations forcing HTTP - Local development without HTTPS setup -3. **Missing authentication** (5% of cases - PHP only) - +3. **Missing authentication configuration** (5% of cases - PHP only) + - No API key, token, authUrl, or authCallback provided - Empty or null authentication parameters ## Resolution Steps 1. **Enable TLS in your configuration** - - - For JavaScript: Set `tls: true` in client options - - For Python: Ensure using HTTPS scheme in connection - - For Ruby: Enable TLS in client configuration - - For Go: Remove `NoTLS` option or set to false - - For PHP: Set `tls` option to true + + ```javascript + // JavaScript + const client = new Ably.Realtime({ + key: 'your-api-key', + tls: true // Enable TLS + }); + ``` + + + **Language-specific implementations:** + - **Python**: Ensure using HTTPS scheme in connection + - **Ruby**: Enable TLS in client configuration + - **Go**: Remove `NoTLS` option or set to false + - **PHP**: Set `tls` option to true 2. **Verify your endpoints** - + - Use `https://rest.ably.io` not `http://rest.ably.io` - Use `wss://realtime.ably.io` not `ws://realtime.ably.io` - Default endpoints already use TLS 3. **Alternative: Use token authentication** - + - Token authentication can work over non-TLS connections - Generate tokens on your secure server - Configure client with `authUrl` or `authCallback` - See [Token Authentication documentation](https://ably.com/docs/auth/token) -4. **For development environments** - +4. **For local development environments** + - Use the sandbox environment which supports TLS - Set up local HTTPS with self-signed certificates - - Or switch to token authentication for local testing + - Switch to token authentication for local testing + - Note: Server-side `allowBasicAuthWithoutTls` setting may not bypass client-side security checks ## Automatic Handling This is a security policy error that will not be automatically retried. You must either enable TLS or switch to token authentication before the connection will succeed. +## Code Examples + +### Secure Development Setup + +```javascript +// Good: Development with TLS enabled +const client = new Ably.Realtime({ + key: process.env.ABLY_KEY, + environment: 'sandbox', // Uses TLS by default + tls: true +}); +``` + +### Token Authentication Alternative + +```javascript +// Alternative: Token auth for environments where TLS isn't available +const client = new Ably.Realtime({ + authCallback: (tokenParams, callback) => { + // Fetch token from your secure server + fetch('/auth/token', { + method: 'POST', + headers: { 'Content-Type': 'application/json' }, + body: JSON.stringify(tokenParams) + }) + .then(response => response.json()) + .then(token => callback(null, token)) + .catch(err => callback(err, null)); + } +}); +``` + ## Prevention - Always use TLS in production environments @@ -95,6 +137,30 @@ This is a security policy error that will not be automatically retried. You must - Use token authentication for client-side applications - Never transmit API keys over unencrypted connections - Configure development environments with HTTPS when possible +- Include security validation in your test suites + +## Performance Impact + +This error prevents connection establishment entirely. There are no performance implications as the connection fails immediately during the security check phase. + +## Related Errors + +• **[40101 - Invalid API Key](https://help.ably.io/error/40101)** + Authentication failures due to incorrect or malformed API keys + +• **[40102 - Token Expired](https://help.ably.io/error/40102)** + Token authentication failures that may require switching to a new token + +• **[40400 - Not Found](https://help.ably.io/error/40400)** + May occur if the app ID or key ID portion of your API key is invalid + +## Related Resources + +- [Authentication documentation](https://ably.com/docs/auth) +- [Basic authentication guide](https://ably.com/docs/auth/basic) +- [Token authentication guide](https://ably.com/docs/auth/token) +- [TLS/SSL encryption](https://ably.com/docs/security) +- [Selecting authentication schemes](https://ably.com/docs/auth/selecting-auth) ## Need Further Help? @@ -111,53 +177,54 @@ When contacting support, please provide: Our team will help you resolve this issue as quickly as possible. -## Related Resources - -- [Authentication documentation](https://ably.com/docs/auth) -- [Basic authentication guide](https://ably.com/docs/auth/basic) -- [Token authentication guide](https://ably.com/docs/auth/token) -- [TLS/SSL encryption](https://ably.com/docs/security) -- Related errors: [40101](./40101-invalid-api-key.mdx), [40102](./40102-token-expired.mdx) - + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/40104-timestamp-not-current.mdx b/src/pages/docs/platform/errors/codes/40104-timestamp-not-current.mdx index 8bef7c0d8c..cbca589cf5 100644 --- a/src/pages/docs/platform/errors/codes/40104-timestamp-not-current.mdx +++ b/src/pages/docs/platform/errors/codes/40104-timestamp-not-current.mdx @@ -1,13 +1,13 @@ - + - + # Error 40104: Timestamp not current @@ -27,6 +27,7 @@ The timestamp in your authentication request is too far from Ably's current serv - Enable `queryTime: true` in your Ably client options to sync with server time - Ensure your server's system clock is synchronized with NTP - Generate fresh token requests instead of caching them +- For Next.js apps, use POST endpoints and disable caching ## Error Messages @@ -42,25 +43,40 @@ The error includes the timestamp deviation in milliseconds when logged server-si - Authentication server's system time has drifted - NTP service not running or misconfigured - Container time not synced with host - + - Virtual machine clock drift + 2. **Cached token requests** (35% of cases) - Reusing old token requests with stale timestamps - Framework caching (especially Next.js 13+) - - Authentication endpoint returning cached responses - + - Authentication endpoint returning cached responses (304 status) + - Build-time token generation in static sites + 3. **Development environment issues** (15% of cases) - Developer machine has incorrect system time - Docker containers with time sync problems - Virtual machine clock drift - + - Time zone misconfigurations + 4. **Network latency** (10% of cases) - Significant delay between token generation and use - Mobile networks with high latency - Temporary network interruptions - + - Geographic distance to Ably endpoints + + +## Diagnostic Patterns + +Understanding the pattern helps identify the root cause: + + +- **Consistent deviation amount**: Clock synchronization issue - timestamps are off by the same amount each time +- **Random deviation amounts**: Caching issue - different timestamps are being reused +- **304 HTTP responses**: Cached resources being served by framework or CDN +- **High volume errors**: Systematic issue affecting all users +- **Post-deployment timing**: Often indicates framework caching configuration issues ## Resolution Steps @@ -71,17 +87,25 @@ The error includes the timestamp deviation in milliseconds when logged server-si key: 'your-api-key' }); ``` - + 2. **Fix your server's system time** ```bash + # Check current time and time zone + date + timedatectl status + # Synchronize system time (Linux/Mac) sudo ntpdate -s time.nist.gov # Enable NTP synchronization sudo systemctl enable ntp + sudo systemctl start ntp + + # Verify NTP synchronization + ntpq -p ``` - + 3. **Generate fresh token requests (don't cache)** ```javascript @@ -90,60 +114,99 @@ The error includes the timestamp deviation in milliseconds when logged server-si app.get('/auth', (req, res) => res.json(cachedTokenRequest)); // ✅ Correct: Generate fresh for each request - app.post('/auth', (req, res) => { - const tokenRequest = ably.auth.createTokenRequest({ + app.post('/auth', async (req, res) => { + const tokenRequest = await ably.auth.createTokenRequest({ timestamp: Date.now(), // Always use current time clientId: req.user.id }); res.json(tokenRequest); }); ``` - + 4. **For Next.js applications** ```javascript + // app/api/auth/route.js + // Use POST to prevent caching export async function POST(request) { const tokenRequest = await ably.auth.createTokenRequest({ timestamp: Date.now(), clientId: await getUserId(request) }); - return Response.json(tokenRequest); + + return Response.json(tokenRequest, { + headers: { + 'Cache-Control': 'no-store, max-age=0' + } + }); } // Disable segment caching export const dynamic = 'force-dynamic'; + export const revalidate = 0; ``` - + 5. **For Docker containers** ```bash - # Use host time + # Option 1: Use host time docker run --volume /etc/localtime:/etc/localtime:ro your-app + + # Option 2: Install NTP in container + # In Dockerfile: + RUN apt-get update && apt-get install -y ntp ``` - + + +6. **Use server time for reliability** + ```javascript + // Query Ably's time when local time is unreliable + const generateToken = async (clientId) => { + const ablyTime = await ably.time(); + + return ably.auth.createTokenRequest({ + timestamp: ablyTime, + clientId: clientId, + ttl: 60000 // Short TTL for security + }); + }; + ``` + ## Automatic Handling This is an authentication error that SDKs do not automatically retry. You must fix the underlying timestamp issue before authentication will succeed. -The Ably server validates timestamps are within an acceptable deviation threshold (configurable server-side) to prevent replay attacks. - +The Ably server validates timestamps are within an acceptable deviation threshold (configured server-side) to prevent replay attacks. The server logs the exact deviation amount for debugging purposes. + ## Prevention -- **Infrastructure**: Enable NTP synchronization on all servers +- **Infrastructure**: Enable NTP synchronization on all servers and containers - **Application**: Never cache token requests - generate fresh for each authentication - **Development**: Keep local machine time accurate and sync Docker containers - **Monitoring**: Set up alerts for time drift on your servers - +- **Framework Configuration**: Disable caching for authentication endpoints +- **API Design**: Use POST for auth endpoints to prevent browser/CDN caching + ## Related Resources - [Token Authentication Guide](https://ably.com/docs/auth/token) - [Client Options Documentation](https://ably.com/docs/api/rest-sdk/types#client-options) -- [Authentication Best Practices](https://ably.com/docs/auth/security) -- Related errors: [40101](./40101-invalid-api-key.mdx), [40102](./40102-token-expired.mdx) +- [Authentication Best Practices](https://ably.com/docs/auth/best-practice) + +## Related Errors + +• **[40101 - Invalid API Key](https://help.ably.io/error/40101)** + Authentication failure due to incorrect or malformed API key + +• **[40102 - Token Expired](https://help.ably.io/error/40102)** + Token has exceeded its TTL and needs renewal + +• **[40103 - Invalid Use of Basic Auth](https://help.ably.io/error/40103)** + Basic authentication attempted over non-TLS connection ## Need Further Help? @@ -157,6 +220,11 @@ When contacting support, please provide: - Steps to reproduce the issue - Any relevant code snippets (without sensitive credentials) - The SDK and version you're using +- **Important diagnostic information**: + - Timestamp deviation amount from logs (if available) + - Whether deviations are consistent or random + - Any 304 HTTP responses in network logs + - Time synchronization status of your servers Our team will help you resolve this issue as quickly as possible. @@ -164,40 +232,59 @@ Our team will help you resolve this issue as quickly as possible. - + + + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/40106-missing-authentication-credentials.mdx b/src/pages/docs/platform/errors/codes/40106-missing-authentication-credentials.mdx index b9150b0b34..90cb4e8637 100644 --- a/src/pages/docs/platform/errors/codes/40106-missing-authentication-credentials.mdx +++ b/src/pages/docs/platform/errors/codes/40106-missing-authentication-credentials.mdx @@ -1,13 +1,13 @@ - + - + # Error 40106: Missing authentication credentials @@ -27,6 +27,7 @@ The Ably SDK cannot find the authentication credentials needed to connect to Abl - Provide an API key when initializing the Ably client - Or configure token authentication with authUrl or authCallback - Check environment variables are properly set in production +- Ensure you're not trying to request a token using another token (requires API key) ## Error Messages @@ -40,36 +41,40 @@ You'll see one of these messages: ## Common Causes 1. **Missing API key** (60% of cases) - + - No key provided during client initialization - Empty string passed as API key - Environment variable not set 2. **Incomplete token authentication setup** (25% of cases) - + - Missing authUrl or authCallback for token auth - Trying to request a token without proper credentials - - Attempting to use a token to request another token + - Attempting to use a token to request another token (requires API key) 3. **Environment configuration issues** (10% of cases) - + - API key not set in production environment - Docker containers missing environment variables - Configuration files not loaded correctly 4. **Wrong authentication method** (5% of cases) - + - Trying to create signed token requests without an API key + - Attempting to request a token using another token instead of an API key - Mixing authentication methods incorrectly ## Resolution Steps 1. **For basic authentication: Add your API key** - + ```javascript // ❌ Wrong: Missing key const ably = new Ably.Realtime({}); + // ❌ Wrong: Empty key + const ably = new Ably.Realtime({ key: "" }); + // ✅ Correct: With API key const ably = new Ably.Realtime({ key: 'your-app-id.your-key-id:your-key-secret' @@ -77,7 +82,7 @@ You'll see one of these messages: ``` 2. **For token authentication: Configure token source** - + ```javascript // Option 1: Auth URL const ably = new Ably.Realtime({ @@ -94,7 +99,7 @@ You'll see one of these messages: ``` 3. **For environment variables: Set and verify** - + ```bash # Set environment variable export ABLY_API_KEY="your-app-id.your-key-id:your-key-secret" @@ -108,15 +113,16 @@ You'll see one of these messages: ``` 4. **Verify your API key format** - + - Check the key follows the format: `app-id.key-id:key-secret` - Ensure no extra spaces or line breaks - Verify the key hasn't expired or been revoked in your dashboard + - Remember: You cannot use a token to request another token 5. **For server-side token generation** - + ```javascript - // Server endpoint to generate tokens + // Server endpoint to generate tokens (requires API key) app.post('/auth', async (req, res) => { const ably = new Ably.Rest({ key: process.env.ABLY_API_KEY }); const tokenRequest = await ably.auth.createTokenRequest(); @@ -124,21 +130,30 @@ You'll see one of these messages: }); ``` +6. **Debug authentication setup** + + ```bash + # Test API key with cURL + curl -u "your-api-key" https://rest.ably.io/time + ``` + ## Automatic Handling This is a configuration error that will not be automatically retried. You must provide valid authentication credentials before the operation will succeed. - + ## Prevention - Store API keys in environment variables, not in code - + - Validate authentication configuration at application startup - + - Use configuration templates for different environments - + - Test authentication setup in all deployment environments - + +- Remember that tokens cannot be used to request other tokens + ## Platform-Specific Notes @@ -146,16 +161,29 @@ This is a configuration error that will not be automatically retried. You must p The error typically occurs during client initialization. Ensure your API key or authentication method is configured before creating the client. ### Java - -Validates during `requestToken()` calls. Requires authCallback, authUrl, or key. + +Validates during `requestToken()` calls. Requires authCallback, authUrl, or key. Returns HTTP 400. ### .NET - + Checks authentication during both AuthOptions construction and auth method creation. May return different HTTP status codes (401 or 404) depending on context. ### Rust - -Validates API key specifically when creating signed token requests. + +Validates API key specifically when creating signed token requests. Returns HTTP 401. + +### Android + +Multiple support incidents report this error during device operations (activation/deactivation). Ensure authentication options are correctly set when creating AblyRest or AblyRealtime instances. + +## Known Issues + +### Android Device Operations + +Some Android clients have reported receiving 40106 errors during device activation/deactivation despite apparently passing tokens correctly. If you encounter this: +- Check all places where AblyRest or AblyRealtime is created +- Verify that either authUrl or authCallback options are properly set +- Ensure tokens are being passed in the expected format ## Related Resources @@ -164,6 +192,17 @@ Validates API key specifically when creating signed token requests. - [Token authentication guide](https://ably.com/docs/auth/token) - [Client options reference](https://ably.com/docs/api/realtime-sdk/client-options) +## Related Errors + +• **[40102 - Token Expired](https://help.ably.io/error/40102)** + Token has expired and needs renewal - different from missing credentials entirely + +• **[40103 - Invalid Use of Basic Auth](https://help.ably.io/error/40103)** + Basic auth attempted over non-TLS connection - requires TLS or token auth + +• **[40140-40149 - Token Errors](https://help.ably.io/error/40140)** + Various token-related errors that may occur after initial authentication + ## Need Further Help? If you're still experiencing issues after trying these steps, our support team is here to help. @@ -183,14 +222,16 @@ Our team will help you resolve this issue as quickly as possible. - + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/40113-account-blocked.mdx b/src/pages/docs/platform/errors/codes/40113-account-blocked.mdx index 056999bdc8..24303bbe6e 100644 --- a/src/pages/docs/platform/errors/codes/40113-account-blocked.mdx +++ b/src/pages/docs/platform/errors/codes/40113-account-blocked.mdx @@ -1,11 +1,11 @@ - + @@ -41,19 +41,19 @@ You may see one of these messages: - Failed payment or expired card - Account delinquency - Billing disputes - + 2. **Terms of Service violations** - Excessive usage beyond plan limits - Abuse or unusual activity patterns - Security concerns - + 3. **Administrative actions** - Manual blocking by Ably support - Automated fraud prevention triggers - Temporary suspension pending verification - + ## Resolution Steps @@ -61,13 +61,13 @@ You may see one of these messages: - Log into your [Ably dashboard](https://ably.com/dashboard) - Look for any account status notifications or warnings - Review your account settings and billing information - + 2. **Review recent communications** - Check email for notifications from Ably support - Look for billing alerts or payment failure notices - Review any security or compliance communications - + 3. **Contact Ably support immediately** - This error requires direct intervention from Ably support @@ -76,18 +76,18 @@ You may see one of these messages: - Provide your account ID - Explain your use case and recent activities - Verify account ownership or business details - + 4. **Address the root cause** - If payment-related: Update billing information - If usage-related: Review and adjust your usage patterns - If security-related: Work with support to verify your account - + ## Automatic Handling This is a terminal authentication error that will not be automatically retried by Ably SDKs. All API operations will fail until the account status is restored. - + ## Prevention @@ -97,7 +97,7 @@ This is a terminal authentication error that will not be automatically retried b - Implement proper rate limiting in your applications - Follow security best practices for API key management - Set up billing alerts in your dashboard - + ## Connection State Impact @@ -106,15 +106,17 @@ When this error occurs: - New connection attempts will fail immediately - Token generation will be blocked - All channels and presence will be unavailable - + ## Related Resources -- [Ably Account Management](https://ably.com/docs/account) - [Ably Terms of Service](https://ably.com/terms) - [Ably Pricing and Plans](https://ably.com/pricing) -- [Authentication documentation](https://ably.com/docs/auth) -- Related errors: [40300](./40300-account-restricted.md) (Account restricted) + +## Related Errors + +• **[40300 - Account Restricted](https://help.ably.io/error/40300)** + Related account limitation that may restrict certain operations but not completely block access ## Need Further Help? @@ -135,11 +137,11 @@ Our team will help you resolve this issue as quickly as possible. - + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/40115-account-request-limit-exceeded.mdx b/src/pages/docs/platform/errors/codes/40115-account-request-limit-exceeded.mdx index 046cbc72d5..3014375e2d 100644 --- a/src/pages/docs/platform/errors/codes/40115-account-request-limit-exceeded.mdx +++ b/src/pages/docs/platform/errors/codes/40115-account-request-limit-exceeded.mdx @@ -1,11 +1,11 @@ - + @@ -112,10 +112,20 @@ The primary production usage is for request limit scenarios as described above. ## Related Resources -- [Ably Rate Limits Documentation](https://ably.com/docs/general/limits) -- [Account Management](https://ably.com/docs/general/account) -- [Best Practices for API Usage](https://ably.com/docs/best-practice) -- Related errors: [42920](./42920-rate-limit-exceeded.md) (per-second rate limits) +- [Ably Documentation](https://ably.com/docs) +- [Account Management](https://ably.com/dashboard) +- [Contact Support](https://ably.com/support) + +## Related Errors + +• **[42922 - Rate Limit Exceeded](https://help.ably.io/error/42922)** + Per-second rate limits, different from account-level hourly quotas + +• **[40100 - Unauthorized Access](https://help.ably.io/error/40100)** + General authentication failures that may occur alongside quota restrictions + +• **[40131 - Key Revoked](https://help.ably.io/error/40131)** + API key revocation that may be related to account restrictions ## Need Further Help? @@ -137,9 +147,10 @@ Our team will help you resolve this issue as quickly as possible. + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/40121-token-revocation-not-enabled.mdx b/src/pages/docs/platform/errors/codes/40121-token-revocation-not-enabled.mdx index 7d941e251d..7be23f947f 100644 --- a/src/pages/docs/platform/errors/codes/40121-token-revocation-not-enabled.mdx +++ b/src/pages/docs/platform/errors/codes/40121-token-revocation-not-enabled.mdx @@ -1,20 +1,20 @@ - + - + # Error 40121: Token revocation not enabled ## What Happened -You attempted to use token revocation features that are not enabled for your Ably application or account. +Your request to revoke tokens was rejected because token revocation features are not enabled for your Ably application or account. ## Quick Reference @@ -36,66 +36,84 @@ You may see one of these messages: ## Common Causes -1. **Token revocation not enabled for application** (most common) - - Your application hasn't been configured with revocation channels - - Token revocation feature not activated for your application - +1. **Application-level token revocation not configured** (70% of cases) + - Your application doesn't have revocation channels set up + - The `app.getRevocationChannels()` configuration returns empty + - Token revocation feature hasn't been activated for your specific application + -2. **Channel-based revocation not enabled** - - Attempting to revoke tokens by channel without the feature flag - - Account doesn't have `revocationByChannel` feature enabled - +2. **Channel-based revocation feature flag disabled** (20% of cases) + - Attempting to revoke tokens by channel without the `revocationByChannel` feature flag + - Your account hasn't been granted access to channel-specific token revocation + - Advanced revocation targeting requires explicit feature enablement + -3. **Plan limitations** - - Current account plan doesn't include token revocation features - - Advanced security features require plan upgrade - +3. **Account plan limitations** (10% of cases) + - Your current Ably plan doesn't include token revocation capabilities + - Advanced security features may require a plan upgrade or enterprise agreement + - Token revocation is typically available on higher-tier plans + ## Resolution Steps -1. **Check your account features** - - Review your current Ably plan to see if token revocation is included - - Visit your [Ably dashboard](https://ably.com/dashboard) to check account features - - Review [Ably pricing plans](https://ably.com/pricing) for feature availability - +1. **Verify your account's token revocation status** + - Log into your [Ably dashboard](https://ably.com/dashboard) + - Navigate to your account settings to check available features + - Review your current plan at [Ably pricing](https://ably.com/pricing) to understand feature availability + - Look for "Token Revocation" or "Advanced Security Features" in your plan details + 2. **Enable token revocation for your account** - - Contact Ably support to enable token revocation features - - Your account manager can help activate advanced security features - - Once enabled, configure revocation settings in your application dashboard - - -3. **Configure application settings** - - Set up revocation configuration in your app settings - - Enable channel-based revocation if needed for your use case - - Ensure revocation channels are properly configured - - -4. **Use alternative security approaches** - - Implement shorter token expiration times (TTL) - - Use capability-based access control to restrict token permissions - - Set up token refresh mechanisms for better security - - Monitor token usage patterns for anomaly detection - + - Contact [Ably support](https://ably.com/support) to request token revocation enablement + - Provide your account ID and specific use case requirements + - If you have an account manager, they can expedite feature activation + - Feature enablement typically takes 1-2 business days + + +3. **Configure revocation settings in your application** + - Once enabled at the account level, access your app settings in the dashboard + - Set up revocation channels configuration for your application + - If you need channel-based revocation, specifically request the `revocationByChannel` feature flag + - Test revocation functionality in your development environment first + + +4. **Implement alternative security strategies while waiting** + - **Shorter token expiration**: Set token TTL to 15-30 minutes instead of hours + - **Granular capabilities**: Restrict tokens to specific channels and operations + - **Token refresh pattern**: Implement automatic token renewal before expiration + - **Audit logging**: Monitor token usage patterns for suspicious activity + - **Client ID restrictions**: Use specific client IDs rather than wildcards + ## Automatic Handling -This is a configuration error that will not be automatically retried. You must enable the feature or use alternative approaches before the operation will succeed. +This is a configuration error that Ably SDKs will not automatically retry. The error indicates a missing feature or permission that requires account or application configuration changes. No amount of retrying will succeed until token revocation is properly enabled. ## Prevention -- Review account features and limitations during application planning -- Understand security requirements before implementation -- Consider token lifecycle management in your application design -- Plan for appropriate account tier based on security needs - +- **During planning**: Review account features and confirm token revocation availability before designing security architecture +- **Before implementation**: Verify that your account plan includes the security features you need +- **Token strategy**: Design your token lifecycle management considering both revocation and expiration approaches +- **Account selection**: Choose an appropriate Ably plan that includes advanced security features if token revocation is critical +- **Feature verification**: Test token revocation in development before relying on it in production + ## Related Resources -- [Token Authentication documentation](https://ably.com/docs/auth/token) -- [Authentication Guide](https://ably.com/docs/auth) +- [Authentication documentation](https://ably.com/docs/core-features/authentication) +- [Token Authentication](https://ably.com/docs/core-features/authentication#token-authentication) - [Ably Pricing Plans](https://ably.com/pricing) -- Related errors: [40101](https://help.ably.io/error/40101), [40102](https://help.ably.io/error/40102) + +## Related Errors + +• **[40101 - Invalid Credentials](https://help.ably.io/error/40101)** + Authentication failed due to invalid API key or token + +• **[40102 - Token Expired](https://help.ably.io/error/40102)** + Token has exceeded its time-to-live and needs renewal + +• **[40103 - Invalid Use of Basic Auth Over Non-TLS](https://help.ably.io/error/40103)** + Basic authentication security requirement not met ## Need Further Help? @@ -116,39 +134,44 @@ Our team will help you resolve this issue as quickly as possible. - + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/40130-key-removed.mdx b/src/pages/docs/platform/errors/codes/40130-key-removed.mdx index 10775d73a2..7515aa9bf0 100644 --- a/src/pages/docs/platform/errors/codes/40130-key-removed.mdx +++ b/src/pages/docs/platform/errors/codes/40130-key-removed.mdx @@ -1,11 +1,11 @@ - + @@ -39,19 +39,19 @@ You may see this error message: - Key deleted through the Ably dashboard - Bulk key cleanup operations - App restructuring or deletion - + 2. **Security-driven removal** (30% of cases) - Compromised key deletion - Security incident response - Preventive key rotation with deletion - + 3. **Account management changes** (10% of cases) - Key management policy changes - Compliance-driven key removal - Account reorganization - + ## Resolution Steps @@ -59,13 +59,13 @@ You may see this error message: - Log into your [Ably dashboard](https://ably.com/dashboard) - Navigate to your app → "API Keys" tab - Confirm the key was removed (it won't appear in the list) - + 2. **Create a replacement API key** - Click "Create a new API key" in the dashboard - Configure the same capabilities as your original key - Copy the complete key including the app ID prefix - + 3. **Update your applications** ```javascript @@ -76,18 +76,18 @@ You may see this error message: - Update all configuration files and environment variables - Replace the key in all client applications - Test connections with the new key - + 4. **Audit all key usage locations** - Review where the removed key was being used - Check server applications, mobile apps, and web clients - Monitor for any authentication failures from missed updates - + ## Automatic Handling This is a permanent authentication failure that will not be automatically retried by Ably SDKs. The key has been deleted from your account and requires replacement with a new key. - + ## Prevention @@ -96,7 +96,7 @@ This is a permanent authentication failure that will not be automatically retrie - Maintain documentation of key usage across applications - Set up monitoring for authentication failures - Follow key rotation best practices without deleting active keys - + ## Security Considerations @@ -105,19 +105,30 @@ If the key was removed due to security concerns: - Review access logs for any unauthorized usage - Consider rotating other keys as a precaution - Update security policies and procedures - + ## Important Note Unlike revoked keys (error 40131) or expired keys (error 40132), removed keys cannot be restored. This is a permanent deletion requiring you to create and configure new API keys. - + + +## Related Errors + +• **[40131 - Key Revoked](https://help.ably.io/error/40131)** + Temporarily disabled key that can be re-enabled through the dashboard + +• **[40132 - Key Expired](https://help.ably.io/error/40132)** + Time-based expiration that requires key renewal or replacement + +• **[40133 - Key Disabled](https://help.ably.io/error/40133)** + Administrative disable that can be reversed by account administrators ## Related Resources -- [API Key Management](https://ably.com/docs/auth/api-key) -- [Authentication Guide](https://ably.com/docs/auth) +- [API Keys Documentation](https://ably.com/docs/account/app/api) +- [Authentication Overview](https://ably.com/docs/auth) - [Basic Authentication](https://ably.com/docs/auth/basic) -- Related errors: [40131 (Key revoked)](./40131-key-revoked.mdx), [40132 (Key expired)](./40132-key-expired.mdx) +- [Control API](https://ably.com/docs/account/control-api) ## Need Further Help? @@ -138,15 +149,15 @@ Our team will help you resolve this issue as quickly as possible. - + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/40131-key-revoked.mdx b/src/pages/docs/platform/errors/codes/40131-key-revoked.mdx index a3b4cf7cc3..fea14942f0 100644 --- a/src/pages/docs/platform/errors/codes/40131-key-revoked.mdx +++ b/src/pages/docs/platform/errors/codes/40131-key-revoked.mdx @@ -1,16 +1,16 @@ - + -# Error 40131: Key revoked +# Error 40131: Key Revoked ## What Happened Your API key has been temporarily suspended (revoked) and cannot be used for authentication until it's restored by an administrator. @@ -35,19 +35,19 @@ You may see one of these messages: ## Common Causes 1. **Administrative suspension** (60% of cases) - + - Key temporarily suspended through dashboard - Precautionary revocation pending review - Policy compliance measures 2. **Security concerns** (25% of cases) - + - Suspected key compromise - Unusual usage patterns detected - Temporary suspension during investigation 3. **Account management** (15% of cases) - + - Key rotation process with temporary revocation - Access control changes - Compliance-related suspension @@ -55,25 +55,25 @@ You may see one of these messages: ## Resolution Steps 1. **Check your API key status** - + - Log into your [Ably dashboard](https://ably.com/dashboard) - Navigate to your app → "API Keys" tab - Look for the key status and any associated messages 2. **Contact your account administrator** - + - If you're not the account owner, reach out to your admin or team lead - Explain when the error started occurring - Provide the affected API key prefix for identification 3. **For account administrators: Contact support** - + - If you're the admin and didn't revoke the key, contact Ably support - Provide context about the key usage and any recent changes - Include any security notifications you may have received 4. **Use an alternative key temporarily** - + - If available, switch to a backup API key - Generate a new key if restoration isn't immediately possible - Update your application configuration with the new credentials @@ -84,21 +84,21 @@ This is a client error that will not be automatically retried. The API key must ## Common Troubleshooting Scenarios ### CI/CD Pipeline Failures - + If your automated tests or deployments are failing with this error: - API keys used in CI/CD may have been revoked during security reviews - Generate dedicated keys for CI/CD environments - Store CI/CD keys securely in environment secrets ### Push Notification Issues - + If device registration or push updates are failing: - This error can affect push notification device registration - The error message may appear as "ARTPushActivationStateMachine: update device failed" - Ensure the key used for push services has not been revoked ### Token Generation Failures - + When generating tokens fails with this error: - A revoked key cannot generate new tokens - This affects both direct token requests and token authentication flows @@ -107,26 +107,32 @@ When generating tokens fails with this error: ## Key Revoked vs Other Key States **Key Revoked (40131)** - Different from other key errors: - + - **Can be restored**: Unlike removed keys (40130), revoked keys can be re-enabled - **Temporary suspension**: Not a permanent deletion - **Maintains configuration**: Original key settings are preserved - **Administrative action**: Requires account admin or support intervention -**Related errors**: -- Error 40130 (Key removed): Permanent deletion, cannot be restored -- Error 40132 (Key expired): Time-based expiration, requires new key -- Error 40133 (Key disabled): Administrative disable, different from revocation - ## Prevention - + - Monitor key usage patterns and alerts in your dashboard - Implement proper key lifecycle management - Use different keys for different environments (development, staging, production) - Set up monitoring for authentication failures - Follow [security best practices](https://ably.com/docs/auth#security-best-practice) for key storage +## Related Errors + +• **[40130 - Key Removed](https://help.ably.io/error/40130)** + Permanent key deletion that cannot be restored, unlike revoked keys + +• **[40132 - Key Expired](https://help.ably.io/error/40132)** + Time-based expiration requiring new key generation + +• **[40101 - Invalid Credentials](https://help.ably.io/error/40101)** + General authentication failure that may occur with incorrect keys + ## Related Resources - [API Key Management](https://ably.com/docs/auth#api-key-authentication) - [Token Authentication](https://ably.com/docs/auth#token-authentication) @@ -151,15 +157,15 @@ Our team will help you resolve this issue as quickly as possible. - + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/40132-api-key-expired.mdx b/src/pages/docs/platform/errors/codes/40132-api-key-expired.mdx index 9a26e7f52f..079afad58c 100644 --- a/src/pages/docs/platform/errors/codes/40132-api-key-expired.mdx +++ b/src/pages/docs/platform/errors/codes/40132-api-key-expired.mdx @@ -1,13 +1,13 @@ - + - + # Error 40132: API key expired @@ -39,19 +39,19 @@ You may see this error message: - Key reached its predetermined expiration date - Time-based security policies automatically enforced - Automated key lifecycle management triggered expiration - + 2. **Forgotten renewal** (15% of cases) - Key expiration date not tracked or monitored - Manual renewal process overlooked - No calendar reminders or monitoring alerts configured - + 3. **Policy changes** (5% of cases) - Security compliance requirements shortened key lifetimes - Organizational key management policies updated - Retroactive policy changes affecting existing keys - + ## Resolution Steps @@ -59,7 +59,7 @@ You may see this error message: - Log into your [Ably dashboard](https://ably.com/dashboard) - Navigate to your app → "API Keys" tab - Identify the expired key and confirm its expiration date - + 2. **Generate a replacement API key** - Click "Create a new API key" in the dashboard @@ -67,26 +67,26 @@ You may see this error message: - Set an appropriate expiration date for the new key - Copy the complete key (including the app ID prefix) - Store the new key securely - + 3. **Update your applications** - Replace the expired key in all client applications - Update configuration files and environment variables - Deploy changes to all environments (development, staging, production) - Document the key change in your deployment logs - + 4. **Test the new key** - Verify connections work with the new key - Test all affected applications and services - Monitor for any authentication errors - Check that all integrations are functioning correctly - + ## Automatic Handling This is an authentication error that will not be automatically retried by Ably SDKs. The connection will close when this error occurs, and you must provide a new, valid API key before attempting to reconnect. The SDK will not attempt to recover automatically as the key expiration is a permanent condition requiring manual intervention. - + ## Prevention @@ -98,7 +98,7 @@ To avoid API key expiration issues: - **Document expiration dates**: Maintain centralized records of all key expiration dates - **Consider longer expiration periods**: Balance security requirements with operational convenience - **Automate where possible**: Use automation tools for key rotation in non-production environments - + ### Best Practices for Key Rotation @@ -108,7 +108,7 @@ To avoid API key expiration issues: 4. **Keep backup keys**: Have replacement keys ready for immediate use 5. **Update documentation**: Ensure all key references are updated 6. **Test thoroughly**: Verify all services after key rotation - + ## Long-Running Applications @@ -118,7 +118,7 @@ For applications that run continuously: - Set up automated restart procedures for key updates - Consider using token authentication with automatic renewal for better key management - Plan maintenance windows for key rotation if necessary - + ## Connection State Impact @@ -138,15 +138,31 @@ ably.connection.on('failed', (stateChange) => { } }); ``` - + + + +## Technical Details + +This error is generated server-side when the Ably realtime server validates API keys. The system detects that a key has reached its expiration timestamp but may not yet be marked as revoked, triggering this specific error code. This validation occurs during connection establishment and authentication operations. + ## Related Resources -- [API Key Management](https://ably.com/docs/auth/api-key) - [Authentication Guide](https://ably.com/docs/auth) +- [Finding your API Keys](https://ably.com/docs/ids-and-keys) - [Token Authentication](https://ably.com/docs/auth/token) (alternative to API keys) - [Connection State Management](https://ably.com/docs/realtime/connection) -- Related errors: [40131 - Key revoked](./40131-key-revoked), [40133 - Key disabled](./40133-key-disabled) + +## Related Errors + +• **[40131 - Key Revoked](https://help.ably.io/error/40131)** + Occurs when an API key has been manually revoked rather than expiring naturally + +• **[40133 - Key Disabled](https://help.ably.io/error/40133)** + API key has been temporarily disabled but not expired or revoked + +• **[40140 - Token Expired](https://help.ably.io/error/40140)** + Similar expiration issue but for token-based authentication rather than API keys ## Need Further Help? @@ -167,17 +183,18 @@ Our team will help you resolve this issue as quickly as possible. - + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/40133-token-revocation-authorization-error.mdx b/src/pages/docs/platform/errors/codes/40133-token-revocation-authorization-error.mdx index df5f2a7e62..be59ebf4a5 100644 --- a/src/pages/docs/platform/errors/codes/40133-token-revocation-authorization-error.mdx +++ b/src/pages/docs/platform/errors/codes/40133-token-revocation-authorization-error.mdx @@ -1,20 +1,20 @@ - + - + # Error 40133: Token revocation authorization error ## What Happened -You're attempting to revoke tokens using a different API key than the one that originally issued them. +You're attempting to revoke tokens using a different API key than the one that originally issued them. This security measure prevents unauthorized token manipulation across different keys. ## Quick Reference @@ -39,19 +39,19 @@ You'll see this exact message: - Using Key B to revoke tokens issued by Key A - Attempting revocation with an administrative key for tokens issued by a service key - Key rotation without proper token tracking - + 2. **Configuration errors** (15% of cases) - Incorrect key selection in revocation requests - Mixed up key IDs in multi-environment setups - Copy-paste errors when setting up revocation requests - + 3. **Process confusion** (5% of cases) - Not tracking which key issued which tokens - Attempting bulk revocation with a single key for tokens from multiple keys - Misunderstanding the token-key relationship requirements - + ## Resolution Steps @@ -59,7 +59,7 @@ You'll see this exact message: - Check your application logs for token issuance records - Review your token tracking system if you have one - Look up the token metadata to find the issuing key ID - + 2. **Switch to the correct key** ```javascript @@ -71,19 +71,19 @@ You'll see this exact message: const ably = new Ably.Rest({ key: 'originalKey.id:secret' }); await ably.auth.revokeTokens({ keyName: 'originalKey.id' }); ``` - + 3. **Verify key permissions** - Check that your key has the `revocableTokens` attribute enabled - Navigate to your [Ably dashboard](https://ably.com/dashboard) → API Keys - Confirm the key has token revocation capabilities - + 4. **Test the revocation** - Attempt revocation with the correct key - Verify tokens are successfully invalidated - Monitor for successful revocation confirmation - + ## Automatic Handling @@ -96,7 +96,7 @@ This is a client error that will not be automatically retried. You must fix the - **Standardize processes**: Establish clear procedures for token lifecycle management - **Key rotation planning**: Before rotating keys, revoke existing tokens with the current key - **Regular audits**: Review token issuance and revocation patterns periodically - + ## Key Rotation Best Practices @@ -107,14 +107,33 @@ When rotating API keys: 3. **After rotation**: Issue new tokens only with the new key 4. **Never mix**: Don't attempt to revoke old tokens with new keys - + + +## Multi-Key Environments + +In complex setups with multiple API keys: +- Assign specific keys for specific purposes (e.g., one for user authentication, another for admin operations) +- Document token issuance responsibilities clearly +- Implement centralized token management if possible +- Use consistent key selection logic throughout your application + + +## Related Errors + +• **[40162 - Token revocation requires basic auth](https://help.ably.io/error/40162)** + Occurs when attempting token revocation without using basic authentication with the issuing key + +• **[40164 - Key lacks revocation capability](https://help.ably.io/error/40164)** + The API key doesn't have the revocableTokens attribute enabled for token revocation + +• **[40121 - Token revocation not enabled](https://help.ably.io/error/40121)** + Token revocation feature is not enabled for the application ## Related Resources - [Token Revocation documentation](https://ably.com/docs/auth/revocation) - [API Key Management](https://ably.com/docs/auth/api-key) - [Authentication guide](https://ably.com/docs/auth) -- Related errors: [40162](https://help.ably.io/error/40162), [40164](https://help.ably.io/error/40164) ## Need Further Help? @@ -135,42 +154,48 @@ Our team will help you resolve this issue as quickly as possible. - + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/40140-token-error-unspecified.mdx b/src/pages/docs/platform/errors/codes/40140-token-error-unspecified.mdx index 54ebb7e2db..92e74e0189 100644 --- a/src/pages/docs/platform/errors/codes/40140-token-error-unspecified.mdx +++ b/src/pages/docs/platform/errors/codes/40140-token-error-unspecified.mdx @@ -1,13 +1,13 @@ - + - + # Error 40140: Token error (unspecified) @@ -24,16 +24,16 @@ Your authentication token could not be validated, and the specific reason couldn ## Quick Fix -- Request a new authentication token from your server +- Request a new authentication token from your server immediately - Verify your token generation process is working correctly - Check that your token hasn't expired or been revoked -- Ensure token has required permissions for the operation +- Ensure the token has required permissions for the operation ## Error Messages You may see one of these messages: - "token error (unspecified)" -- "Token expired" +- "Token expired" - Authentication failure messages with error code 40140 ## Common Causes @@ -42,31 +42,31 @@ You may see one of these messages: - Token has exceeded its TTL (time to live) - Token was valid when created but expired during use - Default TTL is 60 minutes unless specified differently - + 2. **Invalid token format** - Token structure is corrupted or malformed - Token was incorrectly generated or transmitted - Missing required fields in token payload - + 3. **Permission issues** - Token lacks required capabilities for the operation - Token was created with insufficient permissions - Channel requires capabilities not present in token - + 4. **Stale cached token** - SDK using outdated token from cache - Token was revoked but still cached locally - Token refresh failed to update cached credentials - + 5. **Unspecified token problem** - Generic token validation failure - System couldn't determine the specific token issue - Catch-all for uncommon token problems - + ## Resolution Steps @@ -75,14 +75,14 @@ You may see one of these messages: - Ensure the token includes all required capabilities - Replace the expired/invalid token in your client - Verify the new token works with a simple API call - + 2. **Verify token generation** - Check your server-side token creation logic - Ensure you're using the correct API key for token generation - Verify the token request parameters are correct - - Confirm TTL is appropriate for your use case - + - Confirm TTL is appropriate for your use case (default 60 minutes) + 3. **Check required capabilities** - Verify token has permissions for the channel and operation @@ -91,42 +91,50 @@ You may see one of these messages: const tokenRequest = await ably.auth.createTokenRequest({ capability: { 'channel-name': ['publish', 'subscribe', 'presence'] - } + }, + ttl: 3600000 // 60 minutes in milliseconds }); ``` - + + -4. **Implement token refresh** - - Set up automatic token renewal before expiration - - Monitor token TTL and refresh proactively - - Handle token errors gracefully in your application - - Use auth callbacks for automatic renewal: +4. **Implement automatic token refresh** + - Set up auth callbacks for seamless token renewal + - Monitor token TTL and refresh proactively (e.g., at 75% of TTL) + - Handle token errors gracefully in your application: ```javascript const ably = new Ably.Realtime({ authCallback: async (tokenParams, callback) => { - // Fetch new token from your server - const tokenRequest = await fetchTokenFromServer(); - callback(null, tokenRequest); + try { + // Fetch new token from your server + const response = await fetch('/api/ably-token'); + const tokenRequest = await response.json(); + callback(null, tokenRequest); + } catch (error) { + callback(error, null); + } } }); ``` - + + -5. **For SSE connections specifically** +5. **For SSE (Server-Sent Events) connections specifically** + - Detect token errors and reconnect with new token: ```javascript - eventSource.onerror = msg => { + eventSource.onerror = async (msg) => { const err = JSON.parse(msg.data); const isTokenErr = err.code >= 40140 && err.code < 40150; - if(isTokenErr) { + if (isTokenErr) { eventSource.close(); // Fetch new token and reconnect const newToken = await fetchNewToken(); const newUrl = `${baseUrl}?access_token=${newToken}`; eventSource = new EventSource(newUrl); } - } + }; ``` - + ## Automatic Handling @@ -137,10 +145,10 @@ Ably SDKs automatically detect token errors in the 40140-40149 range and: - Trigger token refresh logic when auth callbacks are set up The SDK's behavior varies slightly by implementation: -- **JavaScript**: Uses `isTokenErr()` function for range detection +- **JavaScript**: Uses `isTokenErr()` function for range detection (40140 ≤ code < 40150) - **Java**: Clears token cache and checks for stale tokens specifically - **Python**: Uses `is_token_error()` helper for classification - + ## Prevention @@ -150,29 +158,36 @@ The SDK's behavior varies slightly by implementation: - **Handle the 40140-40149 range**: Set up specific error handling for all token errors - **Use auth callbacks**: Let the SDK handle token renewal automatically - **Clear token cache on errors**: Ensure stale tokens aren't reused - + ## Understanding the Token Error Range -Error 40140 is the first in a range of token-related errors (40140-40149): -- **40140**: Unspecified token error (this error) -- **40141**: Token has been revoked -- **40142**: Token has expired -- **40143**: Token is unrecognized -- **40144**: Invalid JWT format -- **40145**: Invalid token format -- **40146-40149**: Reserved for future token errors +Error 40140 is the first in a range of token-related errors (40140-40149). All errors in this range require obtaining a new, valid token to resolve. + + +## Related Errors + +• **[40141 - Token Revoked](https://help.ably.io/error/40141)** + Token has been explicitly revoked and is no longer valid + +• **[40142 - Token Expired](https://help.ably.io/error/40142)** + Token has exceeded its TTL and needs to be renewed -All errors in this range require obtaining a new, valid token to resolve. - +• **[40143 - Token Unrecognized](https://help.ably.io/error/40143)** + Token is not recognized by the Ably system + +• **[40144 - Invalid JWT Format](https://help.ably.io/error/40144)** + JWT token structure or format is invalid + +• **[40145 - Invalid Token Format](https://help.ably.io/error/40145)** + General token format is invalid or corrupted ## Related Resources - [Token Authentication Documentation](https://ably.com/docs/auth/token) - [Authentication Guide](https://ably.com/docs/auth) - [Token Capabilities](https://ably.com/docs/auth/capabilities) -- [Auth Callbacks](https://ably.com/docs/auth/token#token-refresh) -- Related errors: [40141](./40141-token-revoked.md) through [40149](./40149-token-error.md) (specific token error types) +- [Auth Callbacks for Token Refresh](https://ably.com/docs/auth/token#token-refresh) ## Need Further Help? @@ -194,16 +209,16 @@ Our team will help you resolve this issue as quickly as possible. - + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/40142-token-expired.mdx b/src/pages/docs/platform/errors/codes/40142-token-expired.mdx index 5da70a72fa..6429f684fd 100644 --- a/src/pages/docs/platform/errors/codes/40142-token-expired.mdx +++ b/src/pages/docs/platform/errors/codes/40142-token-expired.mdx @@ -1,13 +1,13 @@ - + - + # Error 40142: Token expired @@ -25,7 +25,7 @@ Your authentication token has expired and is no longer valid for accessing Ably ## Quick Fix - Request a new authentication token from your auth endpoint -- Replace the expired token in your Ably client configuration +- Replace the expired token in your Ably client configuration - Implement automatic token refresh to prevent future expirations ## Error Messages @@ -35,6 +35,7 @@ You may see one of these messages: - "Token expired. (See https://help.ably.io/error/40142 for help.)" - In SSE/HTTP streams: `event: error data: {"message":"Token expired","code":40142,"statusCode":401}` - "Key/token status changed expire" (when connection state changes) +- `ErrorInfo { message: 'Token expired', code: 40142, statusCode: 401 }` (in logs) ## Common Causes @@ -42,19 +43,19 @@ You may see one of these messages: - Token has reached its configured Time-To-Live (TTL) - Long-running sessions exceed token lifetime - Application doesn't refresh tokens proactively - + 2. **Missing token refresh mechanism** (15% of cases) - No automatic token renewal implemented - Token refresh not triggered before expiration - AuthCallback not configured for automatic renewal - + 3. **Network issues** (5% of cases) - Connection drops prevent timely token refresh - Offline periods exceed token lifetime - Network delays in token renewal requests - + ## Resolution Steps @@ -62,19 +63,19 @@ You may see one of these messages: - Call your authentication endpoint or auth callback - Ensure the new token has an appropriate TTL for your use case - Verify the token generation process is working correctly - + 2. **Update your Ably client with the new token** - Replace the expired token in your client configuration - For realtime connections, the SDK will automatically reconnect with the new token - For REST clients, update the token in your next request - + 3. **Implement automatic token refresh** - Set up token renewal when 70-80% of TTL has elapsed - Use Ably's auth callback mechanism for automatic renewal - Handle token refresh failures with appropriate retry logic - + 4. **For client-side applications (e.g., Laravel Broadcasting)** ```javascript @@ -89,8 +90,8 @@ You may see one of these messages: } }); ``` - - + + ## Automatic Handling @@ -105,7 +106,7 @@ If no auth callback is configured, you'll need to manually refresh the token and ## Prevention - **Implement proactive token refresh**: Renew tokens when 70-80% of their TTL has elapsed - + - **Configure appropriate TTL**: Balance security needs with refresh frequency - **Use auth callbacks**: Let Ably SDKs handle token renewal automatically - **Monitor token health**: Track expiration times and refresh patterns @@ -118,24 +119,39 @@ For applications that run continuously: - Implement background token refresh processes - Handle token expiration gracefully during critical operations - Use connection state monitoring to detect authentication failures early - + ## Special Considerations ### Push Notifications -Token expiration in push notification contexts may relate to either JWT tokens or deviceIdentityTokens. Both produce similar error logs, making diagnosis challenging. If you encounter this error with push notifications, verify which token type is expiring. - +Token expiration in push notification contexts may relate to either JWT tokens or deviceIdentityTokens. Both produce similar error logs, making diagnosis challenging. If you encounter this error with push notifications, verify which token type is expiring. Example log: `Rest POST /push/channelSubscriptions subscription access check failed err = ErrorInfo message: Token expired, code: 40142` + ### Android Clients Android applications may experience specific issues with token renewal through AuthCallback. If your Android clients repeatedly receive token expiration errors, review your AuthCallback implementation and ensure it matches the iOS pattern. - + + +### Connection Loop Issues +Clients may enter reconnection loops after token expiration, especially when receiving "Key/token status changed expire" messages. This typically indicates the transport has been superseded with an expired token. Ensure proper token refresh before reconnection attempts. + ## Related Resources -- [Token Authentication documentation](https://ably.com/docs/auth/token) -- [Auth callbacks and token refresh](https://ably.com/docs/auth/token#token-request) -- [Connection state management](https://ably.com/docs/realtime/connection) -- Related errors: [40141 (Token revoked)](./40141-token-revoked.mdx), [40143 (Token unrecognised)](./40143-token-unrecognised.mdx) +- [Ably Authentication Guide](https://ably.com/docs/auth) +- [Token Authentication Documentation](https://ably.com/docs/auth#token-authentication) +- [Connection State Management](https://ably.com/docs/realtime/connection) +- [Laravel Broadcasting with Ably](https://github.com/ably/laravel-broadcaster) + +## Related Errors + +• **[40141 - Token Revoked](https://help.ably.io/error/40141)** + Occurs when a token has been explicitly revoked before its natural expiration + +• **[40143 - Token Unrecognised](https://help.ably.io/error/40143)** + Related error when the provided token format is invalid or corrupted + +• **[40160 - Action Not Permitted](https://help.ably.io/error/40160)** + May occur alongside token errors when attempting unauthorized operations ## Need Further Help? @@ -156,46 +172,50 @@ Our team will help you resolve this issue as quickly as possible. - + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/40144-invalid-jwt-token-format.mdx b/src/pages/docs/platform/errors/codes/40144-invalid-jwt-token-format.mdx index f7e0aa265e..02644bc332 100644 --- a/src/pages/docs/platform/errors/codes/40144-invalid-jwt-token-format.mdx +++ b/src/pages/docs/platform/errors/codes/40144-invalid-jwt-token-format.mdx @@ -1,13 +1,13 @@ - + - + # Error 40144: Invalid JWT token format @@ -47,27 +47,27 @@ You may see one of these messages: ## Common Causes 1. **Missing or invalid timestamps** (60% of cases) - + - JWT missing `iat` (issued at) field - JWT missing `exp` (expires) field - Timestamps not formatted as numbers (e.g., strings or decimals with microseconds) - + 2. **Library-generated format issues** (25% of cases) - + - PHP Lcobucci/JWT library creating timestamps with microseconds - JWT libraries producing string timestamps instead of numbers - Demo token generators with incorrect field types - Python SDK authorization header conflicts with TokenRequest 3. **Invalid capability or configuration** (10% of cases) - + - Empty capability string when specified - Empty revocation key when specified - Unsupported HS384 algorithm 4. **Token nesting issues** (5% of cases) - + - Embedded JWT tokens nested more than once - Invalid embedded access tokens @@ -77,7 +77,7 @@ You may see one of these messages: - Decode your token using [JWT.io](https://jwt.io) or similar tools - Verify the payload contains required fields - Check all field data types match requirements - + 2. **Ensure required fields are correct** Your JWT payload must include: @@ -85,37 +85,37 @@ You may see one of these messages: - `exp`: Unix timestamp as a whole number (e.g., `1234567890`) - If using capability: Must be a non-empty string - If using revocation key: Must be a non-empty string - + 3. **Fix library-specific issues** **For PHP Lcobucci/JWT users:** Configure the library to use integer timestamps only. By default, it creates timestamps with microseconds which Ably rejects. See the [library discussion](https://github.com/lcobucci/jwt/discussions/623) for configuration details. - + **For Kafka Connect/Confluent integration:** Add these converter configurations: - `key.converter: org.apache.kafka.connect.converters.ByteArrayConverter` - `value.converter: org.apache.kafka.connect.converters.ByteArrayConverter` - `value.converter.schemas.enable: false` - + **For Python SDK with auth_url and headers:** If encountering issues with TokenRequest and authorization headers: - Option 1: Return a JWT or Ably token instead of TokenRequest - Option 2: Use auth_callback instead of auth_url - + 4. **Test with a minimal valid token** Create a simple token with only required fields to isolate the issue. - See the [Ably JWT authentication documentation](https://ably.com/docs/auth/token) for token structure requirements. - + See the [Ably JWT authentication documentation](https://ably.com/docs/core-features/authentication#ably-jwt) for token structure requirements. + 5. **Check for unsupported features** - Don't use HS384 algorithm (use HS256 or RS256 instead) - Don't nest JWT tokens more than one level deep - Don't use empty strings for capability or revocation keys - + ## Automatic Handling @@ -128,15 +128,28 @@ This is a client error that will not be automatically retried. You must fix the - Test your token generation with the specific Ably SDK you're using - Monitor authentication failures during development to catch format issues early - Be aware of SDK-specific behaviors (Python vs JavaScript differences) - + ## Related Resources -- [Ably JWT Authentication Guide](https://ably.com/docs/auth/token) -- [Token Generation Documentation](https://ably.com/docs/auth/token#token-request-process) -- [JWT Specification (RFC 7519)](https://tools.ietf.org/html/rfc7519) +- [Ably JWT Authentication Guide](https://ably.com/docs/core-features/authentication#ably-jwt) +- [JWT Authentication Tutorial](https://ably.com/tutorials/jwt-authentication) +- [JWT Specification (RFC 7519)](https://datatracker.ietf.org/doc/html/rfc7519) - [Lcobucci/JWT Configuration Guide](https://github.com/lcobucci/jwt/discussions/623) -- Related errors: [40140](./40140-token-expired), [40141](./40141-token-unrecognized), [40142](./40142-token-revoked) + +## Related Errors + +• **[40140 - Token Expired](https://help.ably.io/error/40140)** + Token has passed its expiration time - differs from 40144 which indicates exp field format issues + +• **[40141 - Token Unrecognized](https://help.ably.io/error/40141)** + Token cannot be parsed at all, while 40144 indicates specific validation failures + +• **[40142 - Token Revoked](https://help.ably.io/error/40142)** + Valid format token that has been revoked, unlike 40144's format issues + +• **[40103 - Invalid Use of Basic Auth](https://help.ably.io/error/40103)** + Authentication method issues that may lead to JWT validation attempts ## Need Further Help? @@ -157,18 +170,21 @@ Our team will help you resolve this issue as quickly as possible. - + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/40146-unsupported-token-claims.mdx b/src/pages/docs/platform/errors/codes/40146-unsupported-token-claims.mdx index 6f22b9287d..432d2887d1 100644 --- a/src/pages/docs/platform/errors/codes/40146-unsupported-token-claims.mdx +++ b/src/pages/docs/platform/errors/codes/40146-unsupported-token-claims.mdx @@ -1,11 +1,11 @@ - + @@ -39,19 +39,19 @@ You'll see this message: - Adding `userClaims` to your token request body - Including `limitsClaims` in server-generated token requests - Attempting to use JWT features only available in client-side generation - + 2. **Migration from custom token generation** - Moving from client-side to server-side token generation without removing unsupported features - Copy-pasting token request code that includes these claims - Assuming all JWT features work with server-side generation - + 3. **Documentation misunderstanding** - Mixing examples meant for client-side and server-side token generation - Not realizing the feature limitations of server-side generation - Following tutorials that use client-side generation patterns - + ## Resolution steps @@ -73,13 +73,13 @@ If these claims aren't essential to your application: capability: { '*': ['publish', 'subscribe'] } }); ``` - + 2. **Use standard token features instead** - Use `clientId` for user identification instead of `userClaims` - Use capabilities for fine-grained access control - Store user-specific metadata in your application - + ### 2. Switch to client-side token generation @@ -89,7 +89,7 @@ If you need `userClaims` or `limitsClaims`: - Use a JWT library in your server code - Sign tokens with your Ably API key secret - Include any JWT claims you need - + 2. **Return signed JWT tokens to clients** - Your backend generates the complete JWT @@ -125,7 +125,7 @@ Consider whether you actually need these advanced claims: 2. **Use clientId** to identify and track users 3. **Store user metadata** in your own database and reference via clientId 4. **Implement custom authorization** in your application layer before issuing tokens - + ## Automatic handling @@ -137,7 +137,7 @@ This is a validation error that occurs before token generation. Ably SDKs will n - **Check feature support** in documentation before implementing token generation - **Test token generation** in development environments first - **Choose the appropriate method** based on your feature requirements - + ## Token generation methods comparison @@ -152,12 +152,12 @@ This is a validation error that occurs before token generation. Ably SDKs will n - `userClaims` and `limitsClaims` supported - More complex implementation required - Complete control over token contents - + ## Real-world context This error has been encountered in production environments, particularly during Project RARE implementation at Ably, where teams attempted to use advanced JWT features with server-generated tokens. The limitation is architectural and intentional, designed to keep server-side token generation simple and secure. - + ## Related resources @@ -165,7 +165,17 @@ This error has been encountered in production environments, particularly during - [Token request API](https://ably.com/docs/api/rest-api#token-request) - [JWT token claims](https://ably.com/docs/auth/token#claims) - [Authentication guide](https://ably.com/docs/auth) -- Related errors: [40001](./40001-bad-request.md) (Invalid token request) + +## Related errors + +• **[40001 - Bad Request](https://help.ably.io/error/40001)** + General validation errors in token requests including invalid types and missing fields + +• **[40101 - Invalid API Key](https://help.ably.io/error/40101)** + API key authentication failures that may require token authentication instead + +• **[40102 - Token Expired](https://help.ably.io/error/40102)** + Token expiration errors that might occur after successful token generation ## Need further help? @@ -186,10 +196,10 @@ Our team will help you resolve this issue as quickly as possible. - @@ -206,23 +216,26 @@ Our team will help you resolve this issue as quickly as possible. + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/40149-token-error-range-boundary.mdx b/src/pages/docs/platform/errors/codes/40149-token-error-range-boundary.mdx index d9cce3162c..5d2a54710d 100644 --- a/src/pages/docs/platform/errors/codes/40149-token-error-range-boundary.mdx +++ b/src/pages/docs/platform/errors/codes/40149-token-error-range-boundary.mdx @@ -1,20 +1,20 @@ - + - + # Error 40149: Token error range boundary ## What Happened -Your authentication token encountered an issue at the boundary of Ably's token error classification range (40140-40149). +Your authentication token encountered an issue that falls at the upper boundary of Ably's token error classification range (40140-40149). ## Quick Reference @@ -24,59 +24,67 @@ Your authentication token encountered an issue at the boundary of Ably's token e ## Quick Fix -- Refresh your authentication token immediately -- Verify the new token has proper permissions +- Request a new authentication token immediately +- Verify the new token has correct capabilities for your operations - Reconnect with the fresh token ## Error Messages -You may see error messages similar to: +You may encounter these error messages: - "Token error (range 40140-40149)" - HTTP 401 response with error code 40149 - Authentication failure at token range boundary +- Token validation failure ## Common Causes -1. **Token validation boundary issue** (Most common) +1. **Token validation boundary issue** (70% of cases) - Token validation failed at the edge of the error range - Authentication system classified the error at range boundary - + - Specific token validation criteria not met + -2. **SDK error classification** +2. **SDK error classification** (20% of cases) - SDK identified a token-related authentication failure - Error fell within the recoverable token error range (40140-40149) - + - Automatic retry logic triggered for token issues + -3. **Token lifecycle event** - - Token expired or became invalid - - Authentication failure requiring token refresh - +3. **Token lifecycle event** (10% of cases) + - Token expired or became invalid during operation + - Authentication failure requiring immediate token refresh + - Token capabilities insufficient for requested operation + ## Resolution Steps 1. **Identify the specific token issue** - - Check for more detailed error information in your logs + - Check your application logs for more detailed error information - Look for specific error codes within the 40140-40149 range - - Review the complete authentication context - + - Review the authentication context and token details + - Verify token expiration time hasn't passed + -2. **Refresh your authentication token** - - Request a new token from your authentication endpoint - - Ensure the new token has the required capabilities - - Verify token generation is working correctly - +2. **Request a fresh authentication token** + - If using token callbacks, ensure your callback returns a valid token + - For server-side token generation, verify your TokenRequest is properly signed + - Check that the new token has required capabilities for your channels + - Ensure clientId matches if using identified clients + 3. **Reconnect with the new token** - - Close the current connection - - Create a new connection with the fresh token - - Verify successful authentication - + - For SSE/EventSource: Close the current connection first + - Create a new connection instance with the fresh token + - Verify successful authentication before resuming operations + - Monitor connection state for successful attachment + 4. **Implement proper error handling** - Set up automatic token refresh for errors in the 40140-40149 range - - Monitor authentication failures - - Log token refresh attempts for debugging - + - Use token callbacks for seamless token renewal + - Monitor authentication failures with proper logging + - Implement exponential backoff for retry attempts + ## Automatic Handling @@ -84,21 +92,34 @@ Ably SDKs automatically recognize errors in the 40140-40149 range as recoverable - Attempt to refresh the token if a token callback is configured - Not treat these as permanent authentication failures - Allow reconnection once a valid token is obtained - +- Maintain message continuity after successful reconnection + ## Prevention - **Implement token lifecycle management**: Set up automatic token refresh before expiration -- **Monitor token validity**: Track token expiration times and refresh proactively -- **Use token callbacks**: Configure your SDK with a callback that provides fresh tokens -- **Handle the 40140-40149 range**: Implement specific error handling for token errors +- **Monitor token validity**: Track token expiration times and refresh proactively (typically 15 minutes before expiry) +- **Use token callbacks**: Configure your SDK with a callback that provides fresh tokens on demand +- **Handle the 40140-40149 range**: Implement specific error handling for all token errors in this range +- **Validate token generation**: Ensure your server-side token generation includes proper capabilities and clientId + +## Related Errors + +• **[40140 - Token Error Range Start](https://help.ably.io/error/40140)** + The beginning of the token error range, indicates initial token validation failures + +• **[40142 - Token Expired](https://help.ably.io/error/40142)** + Specific token expiration error requiring immediate token renewal + +• **[40143 - Token Unrecognized](https://help.ably.io/error/40143)** + Token format or structure not recognized by authentication system ## Related Resources - [Token Authentication](https://ably.com/docs/auth/token) -- [Authentication Best Practices](https://ably.com/docs/auth#best-practice) +- [Authentication Overview](https://ably.com/docs/auth) +- [Token Authentication Best Practices](https://ably.com/docs/core-features/authentication) - [Error Handling Guide](https://ably.com/docs/realtime/usage#error-handling) -- Related errors: [40140](./40140-token-error-range-start.md), [40142](./40142-token-expired.md) ## Need Further Help? @@ -119,41 +140,45 @@ Our team will help you resolve this issue as quickly as possible. - + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/40160-insufficient-capabilities.mdx b/src/pages/docs/platform/errors/codes/40160-insufficient-capabilities.mdx index fed99b77dc..bdbb04f992 100644 --- a/src/pages/docs/platform/errors/codes/40160-insufficient-capabilities.mdx +++ b/src/pages/docs/platform/errors/codes/40160-insufficient-capabilities.mdx @@ -1,13 +1,13 @@ - + - + # Error 40160: Insufficient capabilities @@ -36,37 +36,40 @@ You may see one of these messages: - "Unauthorized to publish messages with privileged extras" - "Access denied to channel: namespace requires TLS connection" - "No authentication options provided; need one of: key, authUrl, or authCallback" +- "Operation [op] unauthorized on channel [channel]" ## Common Causes 1. **Missing channel permissions** (70% of cases) - + - Token lacks `publish`, `subscribe`, or `presence` capabilities for the channel - Attempting operations on channels outside your token's scope - Channel name doesn't match any of your token's capability patterns 2. **Incorrect channel pattern matching** (20% of cases) - + - Wildcard patterns (`*`) don't match actual channel names - Case sensitivity issues in channel names - Namespace prefixes not included in capability patterns + - Remember: wildcards can only replace whole segments delimited by `:` 3. **Special privilege requirements** (10% of cases) - + - Publishing messages with privileged extras without `privileged` capability - Accessing internal channels without privileged keys - TLS-only namespace accessed without TLS connection + - Chat operations requiring specific chat capabilities ## Resolution Steps 1. **Verify your current capabilities** - + - Check the Ably dashboard for your API key's capabilities - For token authentication, decode your JWT to inspect the capability claim - Identify which specific capability is missing for your operation 2. **Update your token capabilities** - + - For token authentication, regenerate with required capabilities: ```javascript const tokenRequest = await ably.auth.createTokenRequest({ @@ -79,49 +82,99 @@ You may see one of these messages: 3. **Fix channel name patterns** - + - Ensure exact match between channel names and capability patterns - - Remember wildcards (`*`) match zero or more characters + - Remember wildcards (`*`) match zero or more characters within segments + - A wildcard at the end can replace many segments (e.g., `namespace:*` matches `namespace:channel:other`) - Check for case sensitivity - channel names are case-sensitive 4. **For privileged operations** - + - Add `privileged` capability for operations with privileged extras: ```javascript capability: { 'privileged:*': ['publish', 'subscribe', 'privileged'] } ``` - + 5. **Check TLS connection requirements** - + - Some namespaces require TLS connections - Ensure your connection uses `https://` or `wss://` protocols - Update connection configuration to use TLS +6. **For filtered subscriptions** + + - Filtered subscriptions require qualified capabilities + - Ensure your token includes the specific channel with appropriate permissions + - Review the [subscription filters documentation](https://ably.com/docs/channels#filter-subscribe) + ## Automatic Handling - + Some Ably SDKs automatically handle this error: - **Laravel Echo**: Detects 40160 and automatically requests an upgraded token with required capabilities - **Asset Tracking SDK**: Implements automatic token renewal when encountering capability failures +- **PubNub Translator**: Silently handles 40160 for leave operations (if you couldn't enter, leaving is allowed) - Other SDKs do not automatically retry as this requires fixing authentication configuration ## Prevention - + - **Plan capabilities carefully**: Include all required permissions when creating tokens - **Use consistent naming**: Establish clear channel naming conventions +- **Understand wildcard patterns**: Know that `*` replaces whole segments delimited by `:` - **Test in development**: Verify token capabilities before production deployment - **Monitor errors**: Track capability-related errors to identify permission gaps +- **Follow least privilege**: Grant only the minimum necessary capabilities for security + +## Common Capability Requirements + + +### Channel Operations +- **Subscribe**: `["subscribe"]` +- **Publish**: `["publish"]` +- **Presence**: `["presence"]` +- **History**: `["history"]` +- **Privileged**: `["privileged"]` (for message extras and internal channels) + +### Capability Inheritance + +- Tokens inherit capabilities from their issuing API key +- A token's capabilities cannot exceed those of the issuing key +- Requested capabilities are intersected with the key's capabilities + +## Debugging Tips + + +1. **Check exact error message** - Look for specific capability or channel mentioned +2. **Verify channel names** - Ensure exact match with capability patterns +3. **Test with admin token** - Try operation with full-capability token to isolate the issue +4. **Review token claims** - Decode JWT tokens to inspect capabilities +5. **Check for stale keys** - Verify API keys haven't been regenerated +6. **Monitor for patterns** - Look for correlated errors like 40142 (token expired) ## Related Resources - [Token Capabilities documentation](https://ably.com/docs/auth/capabilities) - [Authentication guide](https://ably.com/docs/auth) -- [Channel permissions](https://ably.com/docs/realtime/channels#permissions) -- Related errors: [40101](./40101-invalid-api-key.md), [40102](./40102-token-expired.md) +- [Channel permissions](https://ably.com/docs/realtime/channels) +- [Subscription filters](https://ably.com/docs/channels#filter-subscribe) + +## Related Errors + +• **[40101 - Invalid API Key](https://help.ably.io/error/40101)** + Authentication failure due to incorrect or expired API key + +• **[40102 - Token Expired](https://help.ably.io/error/40102)** + Token has expired and needs renewal - often seen alongside capability errors + +• **[40142 - Token Expired](https://help.ably.io/error/40142)** + Another token expiration variant often correlated with 40160 errors + +• **[40103 - Invalid Use of Basic Auth](https://help.ably.io/error/40103)** + Basic authentication used over non-TLS connection ## Need Further Help? @@ -143,14 +196,20 @@ Our team will help you resolve this issue as quickly as possible. + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/40161-namespace-requires-identified-clients.mdx b/src/pages/docs/platform/errors/codes/40161-namespace-requires-identified-clients.mdx index cdc2f66853..5aeea6c086 100644 --- a/src/pages/docs/platform/errors/codes/40161-namespace-requires-identified-clients.mdx +++ b/src/pages/docs/platform/errors/codes/40161-namespace-requires-identified-clients.mdx @@ -1,58 +1,58 @@ - + - + -# Error 40161: Namespace Requires Identified Clients +# Error 40161: Namespace requires identified clients ## What Happened -You're trying to access a channel in a namespace that requires identified clients, but your client doesn't have a valid clientId. +You're trying to access a channel in a namespace that requires client identification, but your client lacks a valid clientId. ## Quick Reference | Error Code | HTTP Status | Category | Retryable | |------------|-------------|----------|-----------| -| 40161 | 401 | Client Error (Authentication) | No - requires configuration fix | +| 40161 | 401 | Client Error (Authentication) | No - requires fixing clientId configuration | ## Quick Fix - Set a clientId when initializing your Ably client -- Use token authentication with a clientId included -- Verify the namespace actually requires identified clients +- Use token authentication with a clientId claim +- Verify the namespace actually requires identification ## Error Messages You may see one of these messages: -- "Access denied to channel: namespace {namespace} requires identified clients (channelId = {channel})" -- The `{namespace}` shows the namespace that requires identification -- The `{channel}` shows the full channel name you're trying to access +- "Access denied to channel: namespace {namespace} requires identified clients (channelId = {channelId})" +- Where `{namespace}` is your namespace name and `{channelId}` is the full channel identifier ## Common Causes -1. **Missing clientId in authentication** (75% of cases) +1. **Missing clientId in configuration** (80% of cases) - Client initialized without clientId parameter - - Anonymous authentication used where identification required - - Token created without clientId field - - -2. **Namespace security configuration** (20% of cases) - - Namespace configured with `identified: true` - - Security policy enforces client identification - - Compliance requirements mandate tracking individual clients - - -3. **SSE connection issues** (5% of cases) - - Server-Sent Events implementation may handle clientId differently - - Known issue with SSE when "Require identification" is enabled - + - Using anonymous authentication where identification is required + - Empty or null clientId provided + + +2. **Token authentication without clientId** (15% of cases) + - Token generated without clientId claim + - Using API key authentication directly without setting clientId + - SSE connections with missing identification + + +3. **Namespace security configuration** (5% of cases) + - Namespace has "Require identification" enabled + - Security policy mandates client identification + - Migrated from public to identified namespace + ## Resolution Steps @@ -64,52 +64,88 @@ You may see one of these messages: // ✅ Correct: Include a unique clientId const ably = new Ably.Realtime({ key: 'your-api-key', - clientId: 'unique-user-id' // e.g., 'user:12345' or email + clientId: 'unique-client-identifier' // e.g., 'user:12345' or email }); ``` - + + + ```python + # Python + from ably import AblyRealtime + client = AblyRealtime(key='your-api-key', client_id='unique-client-identifier') + ``` -2. **For token authentication: Include clientId in token request** + ```ruby + # Ruby + ably = Ably::Realtime.new(key: 'your-api-key', client_id: 'unique-client-identifier') + ``` + +2. **For token authentication, include clientId** ```javascript + // Generate token with clientId const tokenRequest = await ably.auth.createTokenRequest({ - clientId: 'unique-user-id', + clientId: 'unique-client-identifier', capability: { '*': ['publish', 'subscribe'] } }); ``` - + 3. **Verify namespace configuration** - - Check your [Ably dashboard](https://ably.com/dashboard) → App → Settings → Channel rules + - Check your Ably dashboard → App Settings → Channel Rules - Look for the namespace your channel belongs to - Confirm if "Require identification" is enabled - - Consider if this security requirement is necessary for your use case - + - If not needed, consider disabling the requirement + -4. **Choose appropriate clientId patterns** +4. **For SSE connections** + - Ensure TokenRequest includes clientId even for subscribe-only workflows + - Note: SSE may have special handling requirements for identified namespaces + - If issues persist, consider using WebSocket transport instead + + +5. **Choose appropriate clientId patterns** - **User-based**: `user:12345` or `john.doe@example.com` - **Session-based**: `session:abc123def456` - **Service-based**: `backend-service-1` or `api-gateway` - **Anonymous but unique**: `anon:${uuid}` (if you need unique but anonymous) - + ## Automatic Handling -This is a configuration error that will not be automatically retried. The SDK will not attempt to reconnect until you provide valid client identification. +This is a configuration error that will not be automatically retried. The SDK will not attempt to reconnect without proper client identification. You must fix the clientId configuration before the connection will succeed. ## Prevention -- **Plan namespace security**: Determine which channels need client identification during design -- **Document clientId strategy**: Maintain consistent patterns across your application -- **Test authentication**: Verify all clients work with your namespace requirements -- **Avoid sensitive data**: Never use passwords or tokens as clientIds (they're visible to other clients) - +- **Always set clientId** when your application requires user identification +- **Use meaningful identifiers**: `user:12345` or `service:backend-api` +- **Plan namespace security** during application design +- **Test with identification** before enabling namespace requirements +- **Document clientId patterns** for your team + + +## Important Security Note + +The clientId is visible to other clients through presence and message metadata. Never use sensitive information (passwords, tokens, API keys) as clientIds. + ## Related Resources -- [Client identification documentation](https://ably.com/docs/auth/identified-clients) -- [Namespace configuration](https://ably.com/docs/general/channel-rules-namespaces) -- [Authentication guide](https://ably.com/docs/auth) -- Related errors: [40160](./40160-namespace-requires-tls.mdx) (TLS-only namespaces) +- [Authentication documentation](https://ably.com/docs) +- [Channel namespaces documentation](https://ably.com/docs) + +## Related Errors + +• **[40160 - Namespace requires TLS](https://help.ably.io/error/40160)** + Similar namespace security error requiring TLS/SSL connections + +• **[40012 - Invalid Client ID](https://help.ably.io/error/40012)** + Client ID mismatch between message and authenticated connection + +• **[40102 - Token Expired](https://help.ably.io/error/40102)** + Token authentication errors that may affect client identification + +• **[91000 - Presence requires client ID](https://help.ably.io/error/91000)** + Related error when attempting presence operations without identification ## Need Further Help? @@ -130,42 +166,47 @@ Our team will help you resolve this issue as quickly as possible. - + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/40162-token-revocation-requires-basic-auth.mdx b/src/pages/docs/platform/errors/codes/40162-token-revocation-requires-basic-auth.mdx index 375a938b60..fa4dbc537a 100644 --- a/src/pages/docs/platform/errors/codes/40162-token-revocation-requires-basic-auth.mdx +++ b/src/pages/docs/platform/errors/codes/40162-token-revocation-requires-basic-auth.mdx @@ -1,13 +1,13 @@ - + - + # Error 40162: Token revocation requires basic authentication @@ -37,13 +37,13 @@ You may see one of these messages: ## Common Causes 1. **Using token authentication for revocation** (90% of cases) - + - Client authenticated with a token trying to revoke tokens - Frontend application attempting server-side operations - JWT-authenticated requests attempting token management 2. **Architecture issues** (10% of cases) - + - Mixed authentication strategies causing privilege confusion - Client doesn't have access to the original API key - Token-authenticated services trying to manage tokens @@ -51,19 +51,19 @@ You may see one of these messages: ## Resolution Steps 1. **Switch to API key authentication** - + - Ensure your client is initialized with an API key, not a token - API keys start with your app ID followed by a dot and the key ID - Only use API key authentication on secure server-side environments 2. **Move revocation to server-side** - + - Create a server endpoint to handle token revocation - Use API key authentication on your server - Have clients request revocation through your server API 3. **Consider alternatives to revocation** - + - Use shorter token TTL (time-to-live) values - Implement token refresh patterns instead of revocation - Design around token expiration rather than explicit revocation @@ -79,7 +79,7 @@ This is a client error that will not be automatically retried. You must use the ## Prevention - + - **Separate authentication concerns**: Use API keys for administrative operations and tokens for client operations - **Design for token expiration**: Use appropriate token TTL values instead of relying on revocation - **Keep privileged operations server-side**: Never expose API keys to client applications @@ -90,7 +90,23 @@ This is a client error that will not be automatically retried. You must use the - [Token Revocation Documentation](https://ably.com/docs/auth/revocation) - [Authentication Methods](https://ably.com/docs/auth) - [Basic vs Token Authentication](https://ably.com/docs/auth#basic-authentication) -- Related errors: [40101](https://help.ably.io/error/40101), [40102](https://help.ably.io/error/40102), [40103](https://help.ably.io/error/40103) + +## Related Errors + +• **[40101 - Invalid API Key](https://help.ably.io/error/40101)** + Authentication fails when the provided API key is incorrect or malformed + +• **[40102 - Token Expired](https://help.ably.io/error/40102)** + Token has exceeded its TTL and requires renewal through proper authentication + +• **[40103 - Invalid Token](https://help.ably.io/error/40103)** + Token format or signature validation fails during authentication + +• **[40160 - Authentication Error](https://help.ably.io/error/40160)** + Related authentication/authorization error tracked alongside 40162 in monitoring + +• **[40161 - Authorization Failed](https://help.ably.io/error/40161)** + Authorization check fails for the requested operation or resource ## Need Further Help? @@ -112,13 +128,14 @@ Our team will help you resolve this issue as quickly as possible. + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/40164-api-key-missing-revocable-tokens-attribute.mdx b/src/pages/docs/platform/errors/codes/40164-api-key-missing-revocable-tokens-attribute.mdx index b7c44e8449..c6fce9087b 100644 --- a/src/pages/docs/platform/errors/codes/40164-api-key-missing-revocable-tokens-attribute.mdx +++ b/src/pages/docs/platform/errors/codes/40164-api-key-missing-revocable-tokens-attribute.mdx @@ -1,13 +1,13 @@ - + - + # Error 40164: API key missing revocable tokens attribute @@ -39,17 +39,17 @@ You'll see this message: - Standard key generation doesn't include revocation by default - Key was created before token revocation feature was needed - Automated key creation process missing this attribute - + 2. **Using legacy API keys** (8% of cases) - Keys created before revocation feature existed - Keys migrated from older account configurations - + 3. **Feature not available on account plan** (2% of cases) - Token revocation may require specific account features - Advanced security features pending enablement - + ## Resolution Steps @@ -58,7 +58,7 @@ You'll see this message: - Navigate to your app → "API Keys" tab - Look for the `revocableTokens` attribute on your key - Note if the attribute is present and enabled - + 2. **Enable revocation capability on existing key** (if supported) - Click "Edit" on your API key @@ -66,7 +66,7 @@ You'll see this message: - Enable the attribute if available - Save the configuration changes - Test token revocation with the updated key - + 3. **Create a new API key with revocation enabled** - Navigate to "API Keys" → "Create new key" @@ -74,13 +74,13 @@ You'll see this message: - Set other required capabilities (publish, subscribe, etc.) - Save the new key credentials securely - Update your application to use the new key - + 4. **Verify token revocation works** - Test your token revocation implementation - Confirm tokens are successfully revoked - Monitor for any further 40164 errors - + ## Automatic Handling @@ -94,7 +94,23 @@ To avoid this error in the future: - **Use key templates**: Create templates for different use cases with appropriate attributes - **Document key purposes**: Maintain documentation of which keys have which capabilities - **Regular audits**: Review API key configurations periodically - + + +## Performance Impact + +When using revocable tokens: +- Initial connections and REST requests may incur a small latency cost +- The token revocation API is rate-limited per application +- Maximum global aggregate rate is configurable by Ably at the application level + + +## Security Context + +This error is part of Ably's token revocation security framework, which validates: +1. First checks if the key attempting revocation matches the issuing key (error 40133) +2. Then verifies the key has the `revocableTokens` attribute enabled (error 40164) +3. This implements attribute-based access control for privileged operations + ## Alternative Approaches @@ -104,14 +120,21 @@ If token revocation isn't available on your account: - **Implement token refresh**: Use regular token renewal patterns - **Restrict capabilities**: Issue tokens with minimal necessary permissions - **Application-level sessions**: Manage user sessions without relying on token revocation - + ## Related Resources -- [Token Authentication documentation](https://ably.com/docs/auth/token) -- [API Key Management](https://ably.com/docs/auth/basic) -- [Authentication capabilities](https://ably.com/docs/auth/capabilities) -- Related errors: [40133](https://help.ably.io/error/40133) (wrong key for revocation), [40121](https://help.ably.io/error/40121) (revocation not enabled) +- [Token Revocation documentation](https://ably.com/docs/auth/revocation) +- [Authentication overview](https://ably.com/docs/auth) +- [Core features: Authentication](https://ably.com/docs/core-features/authentication) + +## Related Errors + +• **[40133 - Wrong key for revocation](https://help.ably.io/error/40133)** + Occurs when attempting to revoke tokens using a different key than the one that issued them + +• **[40121 - Token revocation not enabled](https://help.ably.io/error/40121)** + Application-level check when token revocation feature is not enabled for the application ## Need Further Help? @@ -132,36 +155,45 @@ Our team will help you resolve this issue as quickly as possible. - + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/40170-auth-callback-error.mdx b/src/pages/docs/platform/errors/codes/40170-auth-callback-error.mdx index 86cd68fa22..ff4e4fe027 100644 --- a/src/pages/docs/platform/errors/codes/40170-auth-callback-error.mdx +++ b/src/pages/docs/platform/errors/codes/40170-auth-callback-error.mdx @@ -1,13 +1,13 @@ - + - + # Error 40170: Authentication callback error @@ -31,44 +31,82 @@ The authentication callback or authUrl failed to provide a valid token for estab ## Error Messages You may see one of these messages: + +**JavaScript/TypeScript:** - "authUrl response is missing a content-type header" - "authUrl responded with unacceptable content-type {type}, should be either text/plain, application/jwt or application/json" +- "authUrl response exceeded max permitted length" +- "Unexpected error processing authURL response; err = {error.message}" - "Token request callback timed out after {timeout} seconds" - "Token string is empty" - "Token string exceeded max permitted length (was {length} bytes)" +- "Token string was literal null/undefined" - "Token was double-encoded; make sure you're not JSON-encoding an already encoded token request or details" -- "Expected token request callback to call back with a token string or token request/details object" +- "Expected token request callback to call back with a token string or token request/details object, but got a {typeof}" +- "Expected token request callback to call back with a token string, token request object, or token details object" +- "Token request/details object exceeded max permitted stringified size (was {size} bytes)" + +**Python:** - "auth_callback raised an exception" -- "Token string was literal null/undefined" +- "Expected token request callback to call back with a token string, token request object, or token details object" +- "Token string was None" +- "auth_url response missing a content-type header" +- "auth_url responded with unacceptable content-type {type}, should be either text/plain, application/jwt or application/json" + +**Java:** +- "Unacceptable content type from auth callback" +- "Unexpected response type from auth callback" +- "Unable to parse response from auth callback" + +**Go:** +- "Error from client token callback" + +**Rust:** +- "authUrl response is missing a content-type header" +- "authUrl responded with unacceptable content-type {type}, should be either text/plain, application/jwt or application/json" +- "token received from authUrl is too long (was {length} bytes, max is {MAX_TOKEN_LENGTH} bytes)" ## Common Causes -1. **Invalid authUrl response headers** (40% of cases) +1. **Invalid authUrl response headers** (35% of cases) - Missing Content-Type header - Using unsupported Content-Type (not text/plain, application/jwt, or application/json) - + - CORS issues preventing header access + + 2. **Auth callback implementation errors** (30% of cases) - Callback returns null, undefined, or empty string - Callback throws an unhandled exception - - Callback returns wrong data type + - Callback returns wrong data type (e.g., returning TokenDetails when token string expected) - Callback returns literal "null" or "undefined" as string - + + 3. **Token size violations** (15% of cases) - - Token exceeds maximum size (64KB for most SDKs, 128KB for Rust) + - Token exceeds maximum size: + - JavaScript, Python, Go: 64KB (65536 bytes) + - Rust: 128KB (131072 bytes) + - Java: No explicit limit - Token request object too large when stringified - + - AuthUrl response body exceeds size limit + + -4. **Double-encoding issues** (10% of cases) - - JSON-encoding an already encoded token +4. **JSON parsing and encoding issues** (10% of cases) + - Double-encoding tokens (JSON-encoding an already encoded token) - Token starts with '{' when Content-Type isn't application/jwt - + - Invalid JSON in authUrl response when Content-Type is application/json + - Missing keyName property in token request objects + -5. **Timeout issues** (5% of cases) - - Auth callback takes longer than timeout (default 10 seconds) +5. **Network and timeout issues** (10% of cases) + - Auth callback takes longer than timeout (default 10 seconds for realtime) - Network latency causes authUrl request to timeout - + - Auth endpoint performance issues in production + - Clock discrepancy between client and server + + ## Resolution Steps @@ -78,7 +116,9 @@ You may see one of these messages: - `text/plain` for token strings - `application/jwt` for JWT tokens - `application/json` for token request objects + - If using CORS, ensure headers are accessible + 2. **Fix auth callback implementation** ```javascript @@ -108,13 +148,17 @@ You may see one of these messages: }; }; ``` - + 3. **Check token size limits** - - Maximum token size: 64KB (65536 bytes) for most SDKs - - Rust SDK allows up to 128KB - - If your tokens are large, consider reducing the claims or using token requests instead - + - Maximum token size varies by SDK: + - JavaScript, Python, Go: 64KB (65536 bytes) + - Rust: 128KB (131072 bytes) + - Java: No explicit limit + - If your tokens are large, consider reducing the claims or using shorter-lived tokens + - For token request objects, the stringified size must also stay within limits + + 4. **Avoid double-encoding** ```javascript @@ -125,7 +169,7 @@ You may see one of these messages: // ✅ Correct: Single encoding return JSON.stringify(tokenRequest); // Properly encoded once ``` - + 5. **Handle errors properly in callbacks** ```javascript @@ -143,7 +187,7 @@ You may see one of these messages: } }; ``` - + 6. **Configure timeout if needed** ```javascript @@ -153,12 +197,23 @@ You may see one of these messages: realtimeRequestTimeout: 15000 // 15 seconds instead of default 10 }); ``` - + + +7. **Debug common issues** + - Enable verbose logging to see the actual auth response + - Check your auth endpoint directly with curl or Postman + - Verify the response format matches what your callback expects + - For Python SDK users: Ensure you're returning the correct type (token string vs TokenDetails object) + ## Automatic Handling This is a client error that will not be automatically retried. The SDK cannot recover from auth callback errors without fixing the underlying implementation issue. +**Note**: Per the RSA4e specification, this error is normalized to HTTP status 401 (Unauthorized) in most SDKs, though Java may use HTTP 406 (Not Acceptable) for certain content-type errors. + + + ## Prevention - **Test auth callbacks thoroughly** before production deployment @@ -167,14 +222,30 @@ This is a client error that will not be automatically retried. The SDK cannot re - **Monitor auth endpoint performance** to catch timeout issues early - **Use proper Content-Type headers** in authUrl responses - **Implement error handling** in auth callbacks - +- **For Python SDK**: Be careful about return types - token string vs TokenDetails +- **For production**: Consider caching tokens appropriately to reduce auth endpoint load + ## Related Resources - [Authentication documentation](https://ably.com/docs/auth) - [Token authentication](https://ably.com/docs/auth/token) - [Auth callbacks guide](https://ably.com/docs/auth/token#token-request) -- Related errors: [40101](./40101-invalid-api-key.md), [40102](./40102-token-expired.md) +- [Auth URL configuration](https://ably.com/docs/auth/token#auth-url) + +## Related Errors + +• **[40101 - Invalid API Key](https://help.ably.io/error/40101)** + Authentication failure due to invalid or missing API key + +• **[40102 - Token Expired](https://help.ably.io/error/40102)** + Token has exceeded its time-to-live and needs renewal + +• **[40140 - Token Error](https://help.ably.io/error/40140)** + General token authentication failures that may trigger callback retry + +• **[80019 - Auth Server Rejecting Request](https://help.ably.io/error/80019)** + Often appears alongside 40170 when auth servers have issues, particularly with clock discrepancy ## Need Further Help? @@ -188,6 +259,7 @@ When contacting support, please provide: - Steps to reproduce the issue - Any relevant code snippets (without sensitive credentials) - The SDK and version you're using +- Logs showing the auth request and response (with sensitive data redacted) Our team will help you resolve this issue as quickly as possible. @@ -195,43 +267,52 @@ Our team will help you resolve this issue as quickly as possible. - + --> \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/40171-token-renewal-not-configured.mdx b/src/pages/docs/platform/errors/codes/40171-token-renewal-not-configured.mdx index 7c8e5d15c8..03cfc555e4 100644 --- a/src/pages/docs/platform/errors/codes/40171-token-renewal-not-configured.mdx +++ b/src/pages/docs/platform/errors/codes/40171-token-renewal-not-configured.mdx @@ -1,13 +1,13 @@ - + - + # Error 40171: Token renewal not configured @@ -25,34 +25,40 @@ Your token has expired and the client cannot renew it because no renewal mechani ## Quick Fix - Reinitialize your client with an API key instead of a static token -- Or add an `authUrl` to enable automatic token renewal +- Or add an `authUrl` to enable automatic token renewal - Or implement an `authCallback` function for custom token renewal ## Error Messages -You may see one of these messages: -- "Need a new token, but authOptions does not include any way to request one (no authUrl, authCallback, or key)" -- "The library was initialized with a token without any way to renew the token when it expires" -- "No means to renew the token is provided (either an API key, authCallback or authUrl)" -- "No means provided to renew auth token" +You may see one of these messages depending on your SDK: +- "Need a new token, but authOptions does not include any way to request one (no authUrl, authCallback, or key)" - JavaScript/Python +- "The library was initialized with a token without any way to renew the token when it expires (no authUrl, authCallback, or key). See https://help.ably.io/error/40171 for help" - .NET +- "No means to renew the token is provided (either an API key, authCallback or authUrl)" - iOS/macOS +- "No means provided to renew auth token" - Rust +- Connection state shows: "failed reason: ErrorInfo... statusCode=403 code=40171" + ## Common Causes 1. **Static token initialization** (90% of cases) - Client initialized with a token literal - No authUrl or authCallback configured - - Token expires after TTL (typically 1 hour) - + - Token expires after TTL (default 1 hour) + - Common when migrating from API key to token auth + 2. **Missing auth configuration** (8% of cases) - Forgot to implement token renewal when migrating from API key auth - Copy-pasted example code without understanding renewal requirements - + - Test environment code deployed to production + -3. **Token validation issues** (2% of cases) +3. **Token validation edge cases** (2% of cases) - Token capability parsing problems - Malformed token structure - + - Token already expired at initialization + - Token validation issues beyond simple expiration + ## Resolution Steps @@ -64,7 +70,7 @@ You may see one of these messages: key: 'your-api-key' }); ``` - + **Option B: Configure authUrl** (recommended for client-side) ```javascript @@ -73,7 +79,7 @@ You may see one of these messages: authMethod: 'POST' }); ``` - + **Option C: Implement authCallback** (most flexible) ```javascript @@ -85,42 +91,73 @@ You may see one of these messages: } }); ``` - + 2. **Create a new client instance** - The failed client cannot be recovered - - Dispose of the old client properly + - Dispose of the old client properly: `client.close()` - Initialize a new client with proper auth configuration - + 3. **Verify token renewal works** - Test that tokens are automatically renewed before expiration - Monitor connection state for successful renewal - Check logs for any renewal warnings + - Test with short TTL tokens in development (e.g., 1 minute) + - Verify renewal occurs before production deployment ## Automatic Handling When this error occurs: -- The connection enters a FAILED state (permanent) +- The connection enters a FAILED state (permanent per RSA4a specification) - No automatic reconnection attempts will be made - Manual intervention is required to create a new client - This behavior is mandated by specification RSA4a - +- The error is intentionally "fail-fast" to prevent confusing silent failures +- Different from token expiration (40140) which SDKs can recover from automatically + + +## Real-World Impact + +This error has affected production systems including: +- **Spotify Artist Room** - Users unable to join parties when tokens weren't renewable +- **Genius Sports** - Python SDK WebSocket transport failures during reauthorization +- **Initial connection failures** - Can occur immediately if token is already expired, not just after TTL + +These cases demonstrate why proper token renewal configuration is critical for production systems. + ## Prevention - **Never use static tokens in production** without a renewal mechanism - **Always implement token renewal** when using token authentication -- **Test token expiration scenarios** before deployment +- **Test token expiration scenarios** before deployment (use short TTL in development) - **Monitor for this error** in production logs to catch configuration issues early - +- **Document your token TTL and renewal strategy** for your team +- **Consider edge cases** - tokens can be invalid for reasons beyond expiration (capability parsing issues) + + +## Related Errors + +• **[40140 - Token Expired](https://help.ably.io/error/40140)** + General token expiration - SDK attempts automatic renewal if configured + +• **[40170 - Auth Callback Failed](https://help.ably.io/error/40170)** + Token renewal was configured but the authCallback encountered an error + +• **[40102 - Invalid Token](https://help.ably.io/error/40102)** + Token format or signature issues rather than renewal configuration + +• **[40103 - Invalid Use of Basic Auth](https://help.ably.io/error/40103)** + Basic auth attempted over non-TLS connection - may occur during auth migration ## Related Resources - [Token Authentication documentation](https://ably.com/docs/auth/token) - [Token Renewal guide](https://ably.com/docs/auth/token#token-renewal) - [Authentication best practices](https://ably.com/docs/auth#best-practice) -- Related errors: [40140](./40140-token-expired.mdx), [40170](./40170-auth-callback-failed.mdx) +- [Connection State Management](https://ably.com/docs/realtime/connection) +- [Error 40171 FAQ](https://faqs.ably.com/error-code-40171-no-means-provided-to-renew-auth-token) ## Need Further Help? @@ -141,47 +178,70 @@ Our team will help you resolve this issue as quickly as possible. - + + + @@ -190,6 +250,6 @@ To improve this error code documentation: 1. First approach: Update editorial-notes.md in ably-os repository with specific guidance for error 40171 2. Regenerate: Run `./bin/ably-os errors document-error-codes 40171 --force` 3. For broader improvements: Review and update ably-os prompt templates -4. Context: See https://github.com/ably/ably-os/blob/main/docs/ERROR_COMMANDS_GUIDE.md +4. Context: See https://github.com/ably/ably-os/blob/5f4ba43/docs/ERROR_COMMANDS_GUIDE.md 5. Source repository: https://github.com/ably/ably-os --> \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/40300-forbidden.mdx b/src/pages/docs/platform/errors/codes/40300-forbidden.mdx index 57e7eaefb8..2fda3f65a9 100644 --- a/src/pages/docs/platform/errors/codes/40300-forbidden.mdx +++ b/src/pages/docs/platform/errors/codes/40300-forbidden.mdx @@ -1,13 +1,13 @@ - + - + --- @@ -32,6 +32,7 @@ Your request was understood but refused because you don't have permission to per - Ensure you're using HTTPS (not HTTP) for Control API requests - Verify your account is active and not disabled - Check that your API key has the required permissions for this operation +- For destructive operations, include the `areYouSure=yes` parameter ## Error Messages @@ -43,9 +44,14 @@ You may see one of these messages: - "unable to publish to qualified channel" - "Disallowed IP address" - "You need to be sure" (for destructive operations) +- "You need to be sure. Go for it, have the courage of your convictions! I believe in you!" +- "Unable to modify channel namespace id with PUT" +- "Unable to modify existing key id with POST" +- "Malformed reauth request" +- "Test routes are disabled in production" - "Forbidden See https://help.ably.io/error/40300" - + ## Common Causes @@ -53,25 +59,31 @@ You may see one of these messages: - Control API accessed via HTTP instead of HTTPS - Security policy requires encrypted connections - Common when migrating from development to production - + 2. **Account or app disabled** (30% of cases) - Account manually disabled by Ably - Application has been disabled - Subscription or billing issues - + 3. **Missing confirmation for destructive operations** (20% of cases) - Administrative operations require "areYouSure=yes" parameter - Protects against accidental deletion or modification - - Common with channel, account, or app management operations - + - Common with channel, account, app management, and database operations + -4. **Insufficient permissions** (10% of cases) +4. **Insufficient permissions** (5% of cases) - API key lacks required capabilities - Feature not available on current plan - Rule type not enabled for account - + + +5. **IP address or security restrictions** (5% of cases) + - IP address blocked for security reasons + - Using localhost or private IPs in production rules + - Test routes accessed in production environment + ## Resolution Steps @@ -85,14 +97,15 @@ const response = await fetch('http://control.ably.net/v1/apps'); // ✅ Correct: Using HTTPS const response = await fetch('https://control.ably.net/v1/apps'); ``` - + ### 2. For disabled account/app errors 1. **Check account status** in your [Ably dashboard](https://ably.com/dashboard) 2. **Verify billing status** - ensure payment methods are up to date -3. **Contact support** if your account shows as disabled without explanation - +3. **Review app status** - check if the specific application is enabled +4. **Contact support** if your account shows as disabled without explanation + ### 3. For missing confirmation parameters @@ -108,7 +121,14 @@ await fetch('https://control.ably.net/v1/apps/appId?areYouSure=yes', { method: 'DELETE' }); ``` - + +This applies to: +- Account deletion or modification +- App deletion or significant changes +- Channel namespace operations +- Network map modifications +- Database operations + ### 4. For permission issues @@ -116,7 +136,7 @@ await fetch('https://control.ably.net/v1/apps/appId?areYouSure=yes', { 2. **Ensure required permissions** are enabled for the operation 3. **Check your account plan** for feature availability 4. **Generate a new key** with appropriate permissions if needed - + ### 5. For IP address restrictions @@ -124,12 +144,27 @@ If you see "Disallowed IP address": - Avoid using localhost or private IPs in production rule configurations - Use publicly accessible URLs for webhooks and integrations - Check if your IP is blocked due to security policies - +- For ADBC (Database Connector) rules, ensure PostgreSQL URIs don't contain localhost + + +### 6. For immutable ID modification errors + +If you see errors about modifying IDs: +- Channel namespace IDs cannot be changed via PUT +- API key IDs cannot be modified via POST +- Notification and rule IDs are immutable +- Create new resources instead of modifying IDs + ## Automatic Handling This is an authorization error that will not be automatically retried by Ably SDKs. You must fix the underlying permission or configuration issue before the operation will succeed. +For SDKs that receive HTTP 403 responses: +- **ably-js**: Normalizes to error 40300 in auth callbacks +- **ably-dotnet**: Defaults to 40300 per RSA4d specification + + ## Prevention - **Always use HTTPS** for Control API and production environments @@ -137,6 +172,8 @@ This is an authorization error that will not be automatically retried by Ably SD - **Implement proper permission management** for different environments - **Add confirmation parameters** to scripts that perform destructive operations - **Monitor account status** to prevent unexpected disabling +- **Use public URLs** for webhooks and integrations, not localhost +- **Test administrative operations** in sandbox environments first ## Related Resources @@ -145,6 +182,17 @@ This is an authorization error that will not be automatically retried by Ably SD - [Authentication guide](https://ably.com/docs/auth) - [Account management](https://ably.com/dashboard) +## Related Errors + +• **[40000 - Bad Request](https://help.ably.io/error/40000)** + General client error that may occur alongside authorization issues + +• **[40100-40170 - Authentication Errors](https://help.ably.io/error/40100)** + Different from authorization - these indicate invalid credentials rather than insufficient permissions + +• **[40400 - Not Found](https://help.ably.io/error/40400)** + May occur when accessing resources that don't exist or you lack permission to view + ## Need Further Help? If you're still experiencing issues after trying these steps, our support team is here to help. @@ -165,42 +213,50 @@ Our team will help you resolve this issue as quickly as possible. + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/40331-placement-constraint-environment.mdx b/src/pages/docs/platform/errors/codes/40331-placement-constraint-environment.mdx index c2d4c2db4c..cac72334a6 100644 --- a/src/pages/docs/platform/errors/codes/40331-placement-constraint-environment.mdx +++ b/src/pages/docs/platform/errors/codes/40331-placement-constraint-environment.mdx @@ -1,13 +1,13 @@ - + - + # Error 40331: Placement constraint environment error @@ -39,15 +39,19 @@ You may see this message: - Connecting to `realtime.ably.io` instead of your custom endpoint - Missing or incorrect environment configuration in client initialization - Using example code without updating to your environment settings + 2. **Misconfigured client library** (8% of cases) - Environment parameter not set or set incorrectly - API key from one environment used with another environment's endpoint - Development configuration used in production + 3. **DNS or routing issues** (2% of cases) - DNS not resolving to correct cluster - Network configuration preventing access to dedicated endpoint + - ATM (Active Traffic Management) failover misconfiguration + ## Resolution Steps @@ -55,7 +59,7 @@ You may see this message: - For enterprise customers with dedicated clusters, you have a custom endpoint - Format: `[environment]-realtime.ably.io` (e.g., `acme-realtime.ably.io`) - Contact your account administrator if you don't know your environment name - + 2. **Configure your client library with the correct environment** ```javascript @@ -68,12 +72,14 @@ You may see this message: environment: 'acme' // Your environment name }); ``` - + 3. **Verify your configuration across all services** - Check all client applications are using the correct environment - Update any hardcoded endpoints in your codebase - Ensure CI/CD pipelines use correct environment variables + - Verify API keys match the target environment + 4. **Test the connection** ```javascript @@ -97,12 +103,23 @@ This is a configuration error that will not be automatically retried. The SDK wi - **Environment variables**: Use configuration files or environment variables rather than hardcoding endpoints - **Code reviews**: Ensure all client initialization code specifies the correct environment - **Testing**: Verify connections in staging environments before production deployment +- **Team communication**: Share environment configurations with all team members ## Related Resources - [Authentication documentation](https://ably.com/docs/auth) - [Connection state management](https://ably.com/docs/realtime/connection) -- Related errors: [40332](./40332-placement-constraint-site.md) (site constraint) + +## Related Errors + +• **[40332 - Placement Constraint Site](https://help.ably.io/error/40332)** + Similar placement constraint error but for site-specific restrictions rather than environment + +• **[40103 - Invalid Use of Basic Auth](https://help.ably.io/error/40103)** + Authentication error that can occur when connecting to wrong environment without TLS + +• **[40400 - Not Found](https://help.ably.io/error/40400)** + May occur if the dedicated cluster endpoint is completely incorrect or doesn't exist ## Need Further Help? @@ -123,34 +140,39 @@ Our team will help you resolve this issue as quickly as possible. - + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/40332-placement-constraint-violation.mdx b/src/pages/docs/platform/errors/codes/40332-placement-constraint-violation.mdx index 8850fb36b6..bb0f970d1b 100644 --- a/src/pages/docs/platform/errors/codes/40332-placement-constraint-violation.mdx +++ b/src/pages/docs/platform/errors/codes/40332-placement-constraint-violation.mdx @@ -1,13 +1,13 @@ - + - + # Error 40332: Placement Constraint Violation @@ -27,82 +27,111 @@ Your application cannot connect to Ably because the account is restricted to a s - Verify you're using the correct regional endpoint for your account - Check if your account has region-specific constraints (EU, China, APAC) - Ensure your SDK configuration includes the custom environment provided +- For China region accounts, use `cn-rest.ably.io` and `cn-realtime.ably.io` ## Error Messages You may see this exact message: - "Unable to activate account due to placement constraint (incompatible site)" +This error appears when your account has placement constraints configured to restrict it to specific data centers or regions. + ## Common Causes 1. **Incorrect endpoint configuration** (80% of cases) - - - Using global endpoint (realtime.ably.io) instead of regional endpoint + + - Using global endpoint (`realtime.ably.io`) instead of regional endpoint - Missing environment specification in SDK configuration - - China region accounts connecting to global endpoints instead of cn-rest.ably.io + - China region accounts connecting to global endpoints instead of `cn-rest.ably.io` + - APAC accounts in `ap-southeast-*` regions using incorrect endpoints 2. **Region mismatch** (15% of cases) - + - Account restricted to EU but connecting without EU environment configuration - - APAC accounts (ap-southeast-*) connecting with global keys + - APAC accounts (`ap-southeast-*`) connecting with global keys - Cross-region connection attempts with incompatible placement constraints + - QoS monitoring failures when global keys lack region-specific constraints 3. **Missing custom environment** (5% of cases) - + - Not using the custom environment provided for your regional account - Using standard API keys instead of region-specific credentials + - Enterprise accounts not specifying their dedicated cluster environment ## Resolution Steps 1. **Identify your account's region** - + - Check your account documentation for regional restrictions - Look for custom environment settings provided when your account was created - - Common regions include: EU, China (CN), APAC (ap-southeast-*) + - Common regions include: + - EU (European Union data centers) + - CN (China region with specific endpoints) + - APAC (`ap-southeast-*` regions like `ap-southeast-4`) + - Contact your customer success manager if unsure about your region 2. **Configure the correct endpoint** - + For standard regions, update your SDK configuration: ```javascript // For EU-restricted accounts const ably = new Ably.Realtime({ key: 'your-api-key', - environment: 'eu' // Add this line + environment: 'eu' // Required for EU placement constraint }); - // For China region + // For China region (CN) const ably = new Ably.Realtime({ key: 'your-api-key', restHost: 'cn-rest.ably.io', realtimeHost: 'cn-realtime.ably.io' }); + + // For APAC regions (e.g., ap-southeast-4) + const ably = new Ably.Realtime({ + key: 'your-api-key', + environment: 'ap-southeast-4' // Your specific APAC region + }); ``` - + 3. **Use custom environments for enterprise accounts** - + - If you were provided a custom environment: + If you were provided a custom environment (common for Enterprise customers): ```javascript const ably = new Ably.Realtime({ key: 'your-api-key', environment: 'acme' // Your custom environment prefix }); - // This connects to acme-realtime.ably.io + // This connects to acme-realtime.ably.io and acme-rest.ably.io ``` 4. **Verify your connection** - + - Test the connection with your regional configuration - Ensure all SDK instances use the same regional settings - Check that API keys match the regional endpoint + - Monitor connection state for successful activation: + ```javascript + ably.connection.on('connected', () => { + console.log('Successfully connected to regional endpoint'); + }); + + ably.connection.on('failed', (stateChange) => { + if (stateChange.reason?.code === 40332) { + console.error('Placement constraint violation - check region config'); + } + }); + ``` + ## Automatic Handling -This error cannot be automatically retried by Ably SDKs as it indicates a configuration issue that must be fixed before the connection can succeed. The SDK will not attempt reconnection until you update the configuration. - +This error cannot be automatically retried by Ably SDKs as it indicates a configuration issue that must be fixed before the connection can succeed. The SDK will not attempt reconnection until you update the configuration with the correct regional settings. + ## Prevention @@ -110,14 +139,34 @@ This error cannot be automatically retried by Ably SDKs as it indicates a config - Document your account's regional constraints for your team - Use the same configuration across all environments (development, staging, production) - Test connections immediately after receiving regional account credentials - +- For China region, always use `cn-*.ably.io` endpoints +- For Enterprise customers, always specify your custom environment + + +## Performance Impact + +This error prevents all realtime operations: +- No messages can be published or received +- Presence updates are blocked +- Channel attachments fail +- The connection remains in a failed state until properly configured + +## Related Errors + +• **[40331 - Environment-level placement constraint](https://faqs.ably.com/error-code-40331-unable-to-activate-account-due-to-placement-constraint-incompatible-environment)** + Similar error but at the environment level rather than site-specific level + +• **[40000 - Bad Request](https://help.ably.io/error/40000)** + May occur alongside placement constraint issues when state is invalid + +• **[40400 - Not Found](https://help.ably.io/error/40400)** + Can occur if the regional endpoint doesn't recognize your app ID ## Related Resources -- [Regional endpoints documentation](https://ably.com/docs/platform-customization/custom-environments) +- [Platform customization documentation](https://ably.com/docs/platform-customization) - [Authentication documentation](https://ably.com/docs/auth) - [Connection state management](https://ably.com/docs/realtime/connection) -- Related error: [40331 - Environment-level placement constraint](https://help.ably.io/error/40331) ## Need Further Help? @@ -131,6 +180,7 @@ When contacting support, please provide: - Steps to reproduce the issue - Any relevant code snippets (without sensitive credentials) - The SDK and version you're using +- Your expected region (EU, China, APAC, or custom environment name) Our team will help you resolve this issue as quickly as possible. @@ -138,43 +188,48 @@ Our team will help you resolve this issue as quickly as possible. - + + + + @@ -183,6 +238,6 @@ To improve this error code documentation: 1. First approach: Update editorial-notes.md in ably-os repository with specific guidance for error 40332 2. Regenerate: Run `./bin/ably-os errors document-error-codes 40332 --force` 3. For broader improvements: Review and update ably-os prompt templates -4. Context: See https://github.com/ably/ably-os/blob/main/docs/ERROR_COMMANDS_GUIDE.md +4. Context: See https://github.com/ably/ably-os/blob/5f4ba43/docs/ERROR_COMMANDS_GUIDE.md 5. Source repository: https://github.com/ably/ably-os --> \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/40400-resource-not-found.mdx b/src/pages/docs/platform/errors/codes/40400-resource-not-found.mdx index 9edd0ad53e..55e9a2b5fe 100644 --- a/src/pages/docs/platform/errors/codes/40400-resource-not-found.mdx +++ b/src/pages/docs/platform/errors/codes/40400-resource-not-found.mdx @@ -1,20 +1,20 @@ - + - + # Error 40400: Resource not found ## What Happened -The requested resource could not be found - most commonly this means your API key is invalid or malformed, though it can also indicate other missing resources like channels, rules, or devices. +The requested resource could not be found. Most commonly, this means your API key is invalid or malformed, though it can also indicate missing channels, rules, devices, or other resources. ## Quick Reference @@ -24,17 +24,17 @@ The requested resource could not be found - most commonly this means your API ke ## Quick Fix -- **Authentication issues**: Check your API key for typos - even one missing character causes this error -- **Wrong environment**: Verify you're using production keys for production, sandbox keys for sandbox -- **Dashboard verification**: Confirm the resource exists in your [Ably dashboard](https://ably.com/dashboard) +- **Check your API key** - Even one missing character causes this error +- **Verify the environment** - Ensure you're using the right keys for production vs sandbox +- **Confirm in dashboard** - Check that the resource exists in your [Ably dashboard](https://ably.com/dashboard) ## Error Messages -You may encounter these messages: +You may encounter one of these messages: - + - "No application found with id {appId}" - Your API key's app ID portion is invalid -- "No key found with id {keyId}" - Your API key's key ID portion is invalid +- "No key found with id {keyId}" - Your API key's key ID portion is invalid - "invalid key parameter" - API key format is incorrect (missing colon separator) - "Device with Id '{deviceId}' is not found" - Push device registration missing - "rule {ruleId} not found" - Integration rule deleted or doesn't exist @@ -45,100 +45,112 @@ You may encounter these messages: ## Common Causes - + -### 1. Invalid API Key Components (Most common - 80% of cases) +### 1. **Invalid API Key Components** (80% of cases) + +API keys have three essential parts: `appId.keyId:keySecret` -**API keys have three parts**: `appId.keyId:keySecret` Example: `xVLyHw.Ke5A1w:dTfJtg-OP2L8B...` +- **App ID**: Before the dot (e.g., `xVLyHw`) +- **Key ID**: Between dot and colon (e.g., `Ke5A1w`) +- **Key Secret**: After the colon (e.g., `dTfJtg-OP2L8B...`) -Common mistakes: -- **Missing characters from app ID** (the part before the dot) → "No application found with id" -- **Missing characters from key ID** (between dot and colon) → "No key found with id" -- **Missing colon separator** → "invalid key parameter" -- **Using a deleted or regenerated key** +**Common mistakes:** +- Missing characters from any part of the key +- Copying an incomplete key +- Using a deleted or regenerated key +- Missing the colon separator entirely -### 2. Wrong Environment or Region (15% of cases) +### 2. **Wrong Environment or Region** (15% of cases) -- Using production API key in sandbox environment -- Using sandbox API key in production environment -- Incorrect regional endpoint (e.g., using US key with EU endpoint) +- Using production API key with sandbox endpoint +- Using sandbox API key with production endpoint +- Incorrect regional endpoint configuration -### 3. Resource Has Been Deleted (5% of cases) +### 3. **Resource Has Been Deleted** (5% of cases) -- API key was regenerated in dashboard (old key no longer valid) -- Push device registration was removed +- API key was regenerated (old key no longer valid) +- Push device registration expired or was removed - Integration rule was deleted - Application was removed from account ## Resolution Steps - + -### 1. Verify Your API Key Structure +### 1. **Verify Your API Key Structure** -API keys must have all three components: -- **App ID**: Before the first dot (e.g., `xVLyHw`) -- **Key ID**: Between dot and colon (e.g., `Ke5A1w`) -- **Key Secret**: After the colon (e.g., `dTfJtg-OP2L8B...`) +Check that your API key has all three components separated correctly: + + +``` +appId.keyId:keySecret +``` - -**Important**: If you see "No application found" or "No key found", your API key is likely missing characters. Even one missing character will cause authentication to fail. +**Important**: Even one missing character will cause authentication to fail. The error message will tell you which part is invalid: +- "No application found" → App ID issue (before the dot) +- "No key found" → Key ID issue (between dot and colon) +- "invalid key parameter" → Missing colon separator -### 2. Check Your Ably Dashboard +### 2. **Check Your Ably Dashboard** - + 1. Log into [https://ably.com/dashboard](https://ably.com/dashboard) 2. Navigate to your app 3. Go to the "API Keys" tab 4. Copy the **complete** key (all three parts) -5. Verify you're in the correct environment: - - **Production**: Uses `rest.ably.io` - - **Sandbox**: Uses `sandbox-rest.ably.io` +5. Verify you're using the correct environment: + - **Production**: Uses `rest.ably.io` or `realtime.ably.io` + - **Sandbox**: Uses `sandbox-rest.ably.io` or `sandbox-realtime.ably.io` -### 3. For Push Device Errors +### 3. **For Push Device Errors** - + +If you see "Device with Id '{deviceId}' is not found": - Navigate to Push Notifications → Devices in your dashboard - Confirm the device ID exists -- Check if the device registration expired +- Check if the device registration has expired - Re-register the device if necessary -### 4. For Integration Rule Errors +### 4. **For Integration Rule Errors** - + +If you see "rule {ruleId} not found": - Go to Integrations in your dashboard - Verify the rule ID exists and is active - Check if the rule was recently modified or deleted - Recreate the rule if needed -### 5. For Pagination Errors +### 5. **For Pagination Errors** - + +If you see "No link to the first/current page of results": - Use the pagination links provided in API responses - Don't manually construct pagination URLs -- Check if the result set is empty (no error, just no results) +- Check if the result set is empty (which is not an error) ## Automatic Handling - -This is a permanent client error that SDKs will not automatically retry. The missing resource must be fixed before the operation can succeed. Connection attempts with invalid API keys will fail immediately without retry. + +This is a permanent client error that SDKs will not automatically retry. The missing resource must be created or the reference must be fixed before the operation can succeed. Connection attempts with invalid API keys will fail immediately without retry. ## Prevention - + - **Store API keys securely**: Use environment variables to avoid typos - **Validate before use**: Check API key format before initialization - **Monitor key rotation**: Update all services when regenerating keys - **Use the dashboard**: Regularly verify resources exist - **Test after changes**: Verify connections after any key regeneration +- **Use complete keys**: Always copy the entire API key including all three parts ## Related Errors • **[40101 - Authentication Failed](https://help.ably.io/error/40101)** - Occurs when API key secret is incorrect (different from 40400's missing resource issue) + Occurs when the API key secret is incorrect (different from 40400's missing resource issue) • **[40103 - Invalid Use of Basic Auth](https://help.ably.io/error/40103)** Related authentication error when using API keys over non-TLS connections @@ -177,46 +189,46 @@ Our team will help you resolve this issue as quickly as possible. - - + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/40500-method-not-allowed.mdx b/src/pages/docs/platform/errors/codes/40500-method-not-allowed.mdx index 61c88be4dc..395d5bffb6 100644 --- a/src/pages/docs/platform/errors/codes/40500-method-not-allowed.mdx +++ b/src/pages/docs/platform/errors/codes/40500-method-not-allowed.mdx @@ -1,11 +1,11 @@ - + @@ -38,67 +38,83 @@ You may see one of these messages: ## Common Causes 1. **Wrong HTTP method for endpoint** (70% of cases) - + - Using GET on a POST-only endpoint - Using POST on a GET-only endpoint - Using PUT or DELETE on endpoints that don't support them 2. **Authentication callback misconfiguration** (20% of cases) - + - Auth callbacks only support GET or POST methods - Using PUT, DELETE, or other methods for auth endpoints + - Attempting to use non-standard HTTP methods 3. **SDK method validation** (10% of cases) - + - Attempting to use methods not supported by the platform - Custom HTTP methods that aren't in the SDK's allowed list + - Client-side validation blocking the request before it's sent ## Resolution Steps 1. **Identify the correct HTTP method** - - - Check the [Ably REST API documentation](https://ably.com/docs/api/rest-api) for endpoint requirements + + - Check the [Ably REST API documentation](https://ably.com/documentation/rest/authentication) for endpoint requirements - Most read operations use GET - Most write operations use POST - Auth endpoints typically require POST for token requests 2. **For authentication callbacks** - + - Ensure your auth callback URL accepts GET or POST only - Configure your server to handle the appropriate method: - GET for simple token requests - POST when sending auth parameters in the body + - Review the code pattern from ably-go which explicitly validates these methods - See [Authentication documentation](https://ably.com/docs/auth) for callback setup 3. **Update your request method** - + - Change the HTTP method in your request configuration - If using an SDK, use the appropriate method call - For REST API calls, specify the correct verb + - Ensure your HTTP client supports the required method 4. **Verify the change** - Make the request with the corrected method - Confirm you receive a successful response - Check that the operation completes as expected + - Monitor for any follow-up authentication issues ## Automatic Handling Ably SDKs do not automatically retry this error as it indicates an incorrect request configuration that must be fixed. The SDK will validate methods before making requests where possible. - + ## Prevention -- Always consult the [REST API documentation](https://ably.com/docs/api/rest-api) for endpoint specifications +- Always consult the [REST API documentation](https://ably.com/documentation/rest/authentication) for endpoint specifications - Use SDK methods rather than raw HTTP requests where possible - For auth callbacks, design your endpoint to accept both GET and POST - Include explicit error handling for 405 responses in your code +- Validate HTTP methods before making requests in your application ## Related Resources -- [REST API Reference](https://ably.com/docs/api/rest-api) +- [REST API Reference](https://ably.com/documentation/rest/authentication) - [Authentication Documentation](https://ably.com/docs/auth) -- [Auth Callback Setup](https://ably.com/docs/auth/token#token-request-callback) -- Related errors: [40101](https://ably.com/docs/errors/40101) (Invalid API Key), [40103](https://ably.com/docs/errors/40103) (Invalid Use of Basic Auth) +- [Auth Callback Setup](https://ably.com/tutorials/token-authentication) + +## Related Errors + +• **[40101 - Invalid API Key](https://help.ably.io/error/40101)** + Authentication failure that may occur alongside method errors when troubleshooting auth callbacks + +• **[40103 - Invalid Use of Basic Auth](https://help.ably.io/error/40103)** + Another authentication configuration error that can appear with incorrect auth setups + +• **[40400 - Not Found](https://help.ably.io/error/40400)** + May occur when the endpoint doesn't exist, before method validation ## Need Further Help? @@ -119,36 +135,41 @@ Our team will help you resolve this issue as quickly as possible. - + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/40800-request-timeout.mdx b/src/pages/docs/platform/errors/codes/40800-request-timeout.mdx index 2cc0a2b9d7..acf5c1b8b6 100644 --- a/src/pages/docs/platform/errors/codes/40800-request-timeout.mdx +++ b/src/pages/docs/platform/errors/codes/40800-request-timeout.mdx @@ -1,13 +1,13 @@ - + - + # Error 40800: Request timeout @@ -26,7 +26,8 @@ Your request to Ably didn't complete within the allowed time limit, resulting in - Check your network connectivity to Ably endpoints - Verify firewall rules aren't blocking connections -- Consider network latency in your region +- Consider network latency if seeing frequent timeouts +- For ping operations, ensure your connection is healthy ## Error Messages @@ -36,72 +37,104 @@ You may see one of these messages: ## Common Causes -1. **Network connectivity issues** (60% of cases) +1. **Network connectivity issues** (50% of cases) - High network latency between client and Ably - Intermittent packet loss - - Network congestion - - -2. **Firewall or proxy interference** (25% of cases) - - Corporate firewall blocking WebSocket connections - - Proxy server introducing delays - - DNS resolution timeouts - - -3. **Server processing delays** (15% of cases) - - Temporary server load conditions - - Large payload processing - - Queue system overload - + - Network congestion affecting request/response times + + +2. **Ping operation timeouts** (25% of cases) + - Connection health check failures + - Server unresponsive to ping requests + - Network path issues to Ably endpoints + + +3. **HTTP request processing delays** (15% of cases) + - Large payload processing times + - Server processing delays during high load + - Response body logging timeouts + + +4. **Queue system timeouts** (10% of cases) + - Queue operations exceeding timeout threshold + - Message processing delays + - Queue system overload conditions + ## Resolution Steps 1. **Verify network connectivity** - - Test connectivity to Ably endpoints (rest.ably.io, realtime.ably.io) - - Check for packet loss or high latency using network diagnostic tools + - Test connectivity to Ably endpoints: + - REST API: `rest.ably.io` + - Realtime: `realtime.ably.io` + - Check for packet loss using network diagnostic tools - Ensure your internet connection is stable - + 2. **Review firewall and proxy settings** - - Ensure WebSocket connections are allowed (port 443) - - Verify Ably domains are whitelisted - - Check proxy timeout settings if applicable - - -3. **Adjust timeout configuration (if available)** + - Ensure port 443 (HTTPS/WebSocket) is open for Ably domains + - Whitelist these domains: + - `*.ably.io` + - `*.ably-realtime.com` + - `ws-up.ably-realtime.com` (for WebSocket connectivity checks) + - Check proxy timeout settings if using a proxy server + - Confirm DNS resolution is working correctly + + +3. **For ping timeout issues specifically** + - Monitor connection state before attempting ping operations + - Consider implementing custom health check intervals + - Use connection state listeners to detect issues proactively + + +4. **Adjust timeout configuration (if available)** - Some SDKs allow configuring timeout values - Increase timeout for high-latency environments - - Balance between responsiveness and reliability - + - Balance between responsiveness and reliability based on your network conditions + -4. **Monitor for patterns** - - Check if timeouts occur at specific times - - Look for correlation with network events +5. **Monitor for patterns** + - Check if timeouts occur at specific times of day + - Look for correlation with network events or maintenance windows - Track timeout frequency to identify systemic issues - + - Review application logs for timeout patterns + ## Automatic Handling Ably SDKs implement automatic retry logic for timeout errors: -- The SDK will retry the request with appropriate backoff -- Connection recovery mechanisms handle transient network issues +- The SDK will retry the request with appropriate backoff strategies +- Connection recovery mechanisms handle transient network issues automatically - You don't need to implement manual retry logic for most timeout scenarios - +- Ping operations will be retried as part of connection health monitoring + ## Prevention - **Monitor network quality**: Regularly check connection quality to Ably endpoints -- **Configure appropriate timeouts**: Set timeout values based on your network conditions +- **Configure appropriate timeouts**: Set timeout values based on your network conditions and use case - **Use connection state listeners**: Monitor connection state to detect issues early - **Implement fallback strategies**: Have contingency plans for degraded network conditions - +- **Optimize payload sizes**: Keep message sizes reasonable to avoid processing delays + ## Related Resources -- [Connection state management](https://ably.com/docs/realtime/connection) -- [Network requirements](https://ably.com/docs/best-practice/network-requirements) +- [Connection state and recovery](https://ably.com/docs/connect/states) +- [Connections overview](https://ably.com/docs/connect/) +- [Firewall and network requirements FAQ](https://faqs.ably.com/if-i-need-to-whitelist-ablys-servers-from-a-firewall-which-ports-ips-and/or-domains-should-i-add) - [Ably status page](https://status.ably.com) -- Related errors: [50003](./50003-server-timeout.md) (server timeout), [80002](./80002-connection-suspended.md) (connection suspended) + +## Related Errors + +• **[50003 - Server Timeout](https://help.ably.io/error/50003)** + Server-side timeout when processing exceeds limits + +• **[80002 - Connection Suspended](https://help.ably.io/error/80002)** + Connection enters suspended state after 2 minutes of failed attempts + +• **[80008 - Connection Recovery Failed](https://help.ably.io/error/80008)** + Unable to recover connection when resume window expires ## Need Further Help? @@ -122,42 +155,48 @@ Our team will help you resolve this issue as quickly as possible. - + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/42211-message-rejected-before-publish-rule.mdx b/src/pages/docs/platform/errors/codes/42211-message-rejected-before-publish-rule.mdx index 36ac69f439..11a6eb7b3d 100644 --- a/src/pages/docs/platform/errors/codes/42211-message-rejected-before-publish-rule.mdx +++ b/src/pages/docs/platform/errors/codes/42211-message-rejected-before-publish-rule.mdx @@ -1,20 +1,20 @@ - + - + # Error 42211: Message rejected by before-publish rule ## What Happened -Your chat message was blocked by a custom validation rule configured for this chat room. +Your chat message was blocked by a custom validation rule configured for this chat room before it could be published. ## Quick Reference @@ -25,30 +25,30 @@ Your chat message was blocked by a custom validation rule configured for this ch ## Quick Fix - Review your message content for any restrictions -- Check the chat room's configured rules with your development team +- Check with your development team about the chat room's configured rules - Modify your message to comply with the room's requirements ## Error Messages -You may see this message: +You will see this message: - "The message was rejected before publishing by a rule on the chat room" ## Common Causes 1. **Content policy violations** (60% of cases) - + - Message contains prohibited words or phrases - URLs are restricted in this chat room - Message format doesn't meet requirements 2. **Business rule violations** (30% of cases) - + - Message exceeds length limits - User has exceeded rate limits for this room - Messages are restricted during certain time periods 3. **Custom filter violations** (10% of cases) - + - Room-specific rules are in place - Application has custom compliance requirements - Special policies apply to this chat context @@ -56,25 +56,25 @@ You may see this message: ## Resolution Steps 1. **Review your message content** - + - Check for any words or patterns that might be restricted - Verify URLs are allowed if your message contains links - Ensure message length is within acceptable limits 2. **Understand the room rules** - + - Contact your development team for room rule documentation - Check if there are time-based restrictions - Verify any user-specific limitations 3. **Modify and retry** - + - Adjust your message to comply with known restrictions - Remove or modify any flagged content - Try sending a simplified version of your message 4. **For developers: Review rule configuration** - + - Verify before-publish rules are configured appropriately - Consider implementing client-side validation to prevent rejections - Provide clear user feedback about message requirements @@ -83,24 +83,40 @@ You may see this message: ## Automatic Handling This is a client error that will not be automatically retried. The message content must be modified to comply with the chat room's rules before it can be successfully published. - + ## Prevention - **For users**: Familiarize yourself with any chat room guidelines - **For developers**: - + - Implement client-side pre-validation to catch violations before sending - Provide clear communication about room rules to users - Consider progressive validation (warn before rejecting) - Use informative error messages that explain specific violations +## Technical Context + + +This error is part of Ably Chat's two-tier validation system that allows developers to configure custom rules for chat rooms. These before-publish rules execute before messages are published, providing flexible content control mechanisms separate from automated moderation (error 42213). + +The error is currently implemented in: +- **Ably Chat SDK for Android** (ably-chat-kotlin) +- **Ably Chat SDK for iOS** (ably-chat-swift) + ## Related Resources - [Ably Chat documentation](https://ably.com/docs/chat) - [Ably Chat SDK for Android](https://github.com/ably/ably-chat-kotlin) - [Ably Chat SDK for iOS](https://github.com/ably/ably-chat-swift) -- Related error: [42213 - Message rejected by moderation](https://ably.com/docs/errors/42213) + +## Related Errors + +• **[42213 - Message rejected by moderation](https://help.ably.io/error/42213)** + Automated content moderation rejected the message for safety or compliance reasons + +• **[40001 - Invalid request body](https://help.ably.io/error/40001)** + General validation failure for malformed requests to the Chat API ## Need Further Help? @@ -121,11 +137,11 @@ Our team will help you resolve this issue as quickly as possible. - @@ -149,8 +165,12 @@ Our team will help you resolve this issue as quickly as possible. - Step 3: Knowledge file lines 27-31 about modifying message to comply - Step 4: Knowledge file lines 68-74 developer guidance for configuration - Prevention: Based on knowledge file lines 33-38 (best practices) and 68-74 (developer guidance) +- Technical Context: Based on analysis file lines 54-61 explaining two-tier validation system --> + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/42213-message-rejected-by-moderation.mdx b/src/pages/docs/platform/errors/codes/42213-message-rejected-by-moderation.mdx index daf81871c7..61e837069b 100644 --- a/src/pages/docs/platform/errors/codes/42213-message-rejected-by-moderation.mdx +++ b/src/pages/docs/platform/errors/codes/42213-message-rejected-by-moderation.mdx @@ -1,11 +1,11 @@ - + @@ -40,24 +40,26 @@ You'll see this message: - Explicit language or masked profanity - Offensive terms or slurs - Inappropriate sexual content - + 2. **Toxic behavior** - Harassment or bullying - Threats or aggressive language - Hate speech or discrimination - + 3. **Spam or repetitive content** - Excessive repetition - Commercial spam or promotions - Link spam or unauthorized URLs - + 4. **Channel-specific policy violations** - Content inappropriate for the specific room context - Violations of custom moderation rules - + - Content exceeding configured toxicity thresholds + + ## Resolution Steps @@ -65,37 +67,49 @@ You'll see this message: - Identify potentially problematic language - Check for any terms that might trigger moderation - Consider the context and audience of the chat room - + 2. **Revise your message** - Remove or replace inappropriate language - Ensure the message is respectful and constructive - Avoid excessive repetition or promotional content - + 3. **Retry sending** - Send your revised message - If still rejected, consider further revision - Check if you're following room-specific guidelines - + 4. **If legitimate content is being blocked** - The message may be a false positive - Try rephrasing in a different way - Contact the application support team if the issue persists - + ## Automatic Handling This error is not automatically retried by Ably SDKs. The message content must be revised before it can be successfully published. The moderation check happens before the message is distributed to other users, protecting the community from inappropriate content. - + + +## Moderation Services + +Ably Chat integrates with several AI-powered moderation services that may trigger this error: + +- **Hive Moderation**: AI text analysis with configurable severity thresholds +- **Bodyguard**: Contextual analysis with channel-specific rules +- **Tisane**: Advanced content moderation capabilities + +Each service can be configured per chat room with custom thresholds and policies. + + ## Prevention - **Familiarize yourself with community guidelines** - Understand the chat room's content policies - Be aware of language that might trigger moderation - + - **Write respectfully** - Use appropriate language for the audience @@ -107,13 +121,19 @@ This error is not automatically retried by Ably SDKs. The message content must b - Display user-friendly error messages - Offer content guidelines to users - Consider client-side pre-filtering for common violations - + - Monitor false positive rates and adjust thresholds if needed + ## Related Resources -- [Ably Chat Moderation documentation](https://ably.com/docs/chat/moderation) -- [Ably Chat SDK documentation](https://ably.com/docs/chat) -- [Content moderation best practices](https://ably.com/docs/chat/moderation#best-practices) +- [Ably Chat documentation](https://ably.com/docs/chat) +- [AI moderation FAQ](https://faqs.ably.com/ai-chat-moderation) +- [Hive Dashboard moderation](https://ably.com/docs/chat/moderation/direct/hive-dashboard) + +## Related Errors + +• **[42211 - Message Rejected by Before-Publish Rule](https://help.ably.io/error/42211)** + General before-publish rule rejection not specific to AI moderation ## Need Further Help? @@ -134,32 +154,36 @@ Our team will help you resolve this issue as quickly as possible. - + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/42922-rate-limit-too-many-requests.mdx b/src/pages/docs/platform/errors/codes/42922-rate-limit-too-many-requests.mdx index 31044d3060..6ad749db74 100644 --- a/src/pages/docs/platform/errors/codes/42922-rate-limit-too-many-requests.mdx +++ b/src/pages/docs/platform/errors/codes/42922-rate-limit-too-many-requests.mdx @@ -1,13 +1,13 @@ - + - + # Error 42922: Rate limit exceeded - too many requests @@ -42,24 +42,30 @@ You may see one of these messages: - Burst of chat messages requiring moderation - Spam attack triggering multiple moderation checks - Popular live event generating excessive traffic - + 2. **Lambda function rate limiting** (25% of cases) - Too many concurrent Lambda invocations - AWS account Lambda limits reached - Lambda function throttling - + -3. **Account quota exceeded** (15% of cases) +3. **CloudFront rate limiting** (10% of cases) + - Infrastructure-level rate limiting + - Protection against excessive request patterns + - Regional traffic spikes + + +4. **Account quota exceeded** (5% of cases) - Moderation quota limit reached for your plan - Trial account restrictions - Monthly limits exhausted - + ## Resolution Steps 1. **Implement exponential backoff** - + ```javascript let delay = 1000; // Start with 1 second const maxDelay = 32000; // Cap at 32 seconds @@ -79,7 +85,7 @@ You may see one of these messages: } } ``` - + 2. **Check rate limit headers** Monitor response headers to track your usage: @@ -87,26 +93,28 @@ You may see one of these messages: - `X-RateLimit-Remaining`: Requests remaining - `X-RateLimit-Reset`: When the limit resets - `Retry-After`: Suggested wait time (if present) - + - `x-ably-errorcode`: Will show 42922 + - `x-ably-errormessage`: Contains specific error message + 3. **Optimize request patterns** - Batch operations where possible - Implement client-side filtering to reduce moderation calls - Cache frequently accessed Lambda results - Distribute load across time windows - + 4. **Consider plan upgrade** If you consistently hit rate limits: - Review your current plan limits - Contact sales for higher quotas - Consider dedicated infrastructure options - + ## Automatic Handling This is a rate limit error that requires exponential backoff for retry. Ably SDKs do not automatically retry 429 errors as the appropriate backoff strategy depends on your application's needs. You must implement your own retry logic with exponential backoff. - + ## Prevention @@ -114,14 +122,28 @@ This is a rate limit error that requires exponential backoff for retry. Ably SDK - **Implement request queuing**: Buffer and throttle requests during high-traffic periods - **Monitor usage patterns**: Track your rate limit consumption to predict and prevent hitting limits - **Use webhooks for async processing**: Instead of synchronous Lambda calls, consider webhook-based patterns - +- **Implement caching strategies**: Cache Lambda responses and moderation results where appropriate + ## Related Resources - [Ably Rate Limits Documentation](https://ably.com/docs/general/limits) - [Moderation Documentation](https://ably.com/docs/chat/moderation) - [Integrations Guide](https://ably.com/docs/general/integrations) -- Related errors: [42910](./42910-rate-limit-exceeded.md) (non-fatal rate limit), [42920](./42920-rate-limit-fatal.md) (fatal rate limit) + +## Related Errors + +• **[42910 - Rate limit exceeded (non-fatal)](https://help.ably.io/error/42910)** + Non-fatal rate limit for general operations where connection remains open + +• **[42911 - Rate limit exceeded per connection publish](https://help.ably.io/error/42911)** + Specific to per-connection publish rate limits, connection stays active + +• **[42920 - Rate limit exceeded (fatal)](https://help.ably.io/error/42920)** + Fatal rate limit that causes connection closure + +• **[42921 - Rate limit exceeded per connection publish (fatal)](https://help.ably.io/error/42921)** + Fatal per-connection publish limit causing connection termination ## Need Further Help? @@ -142,11 +164,11 @@ Our team will help you resolve this issue as quickly as possible. - @@ -155,23 +177,28 @@ Our team will help you resolve this issue as quickly as possible. - Content Excluded: None - all relevant information included - Recommendations Source: - Exponential backoff: Editorial notes line 26 (specifically allowed for 429 errors) - - Rate limit headers: Standard practice for 429 errors + - Rate limit headers: Standard practice for 429 errors plus knowledge file lines 68-74 - Client-side filtering: Knowledge file line 34 - Plan upgrade: Knowledge file line 29 + - CloudFront headers: Knowledge file lines 68-74 - Code Examples Rationale: Included exponential backoff code as it's essential for 429 error handling per editorial notes --> + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/49900-call-cancelled.mdx b/src/pages/docs/platform/errors/codes/49900-call-cancelled.mdx index 2064826a85..dcdd2d14a8 100644 --- a/src/pages/docs/platform/errors/codes/49900-call-cancelled.mdx +++ b/src/pages/docs/platform/errors/codes/49900-call-cancelled.mdx @@ -1,16 +1,16 @@ - + - + -# Error 49900: Call cancelled +# Error 49900: Call Cancelled ## What Happened @@ -35,43 +35,55 @@ You may see this message: ## Common Causes -1. **Client-initiated cancellation** (most common) +1. **Client-initiated cancellation** (80% of cases) - User navigated away from the page - Application explicitly cancelled the request - SDK cleanup during shutdown - + - Browser tab was closed or refreshed + -2. **Client timeout** +2. **Client timeout** (15% of cases) - Request exceeded client-side timeout settings - Network interruption caused timeout - Connection lost before operation completed - + - Temporary network connectivity issues + -3. **Application lifecycle events** +3. **Application lifecycle events** (5% of cases) - App was backgrounded or suspended - - Browser tab was closed + - Browser tab lost focus or entered background - Application shutdown initiated - + - Device entered sleep mode + ## Resolution Steps 1. **Determine if the cancellation was intentional** - - Check if the user initiated the cancellation + - Check if the user initiated the cancellation (page navigation, app close) - Verify if the application is shutting down gracefully - Review client timeout settings - + - Look for patterns in when cancellations occur + 2. **For unintentional cancellations** - Review and adjust client timeout settings if too aggressive - - Check network stability + - Check network stability and connectivity - Ensure proper error handling for connection interruptions + - Consider implementing retry logic for critical operations 3. **For application lifecycle issues** - Implement proper cleanup in your application shutdown handlers - Save state before operations that might be interrupted - Consider using background tasks for critical operations - + - Handle page visibility changes appropriately + + +4. **Monitor and log occurrences** + - Track when these errors occur to identify patterns + - Log the context (user action, network state, app state) + - Use this data to improve timeout settings + ## Automatic Handling @@ -79,7 +91,8 @@ This error represents expected behavior when clients cancel operations. The Ably - Clean up resources automatically - Not retry cancelled operations (as they were intentionally cancelled) - Allow you to retry manually if the operation is still needed - +- Maintain connection state for other operations + ## Prevention @@ -87,12 +100,26 @@ This error represents expected behavior when clients cancel operations. The Ably - Implement proper cleanup in error handlers - Consider whether operations need to complete even if the user navigates away - Use appropriate timeout values for your use case - +- Handle browser/app lifecycle events properly +- Consider using persistent connections for critical operations + ## Related Resources - [Connection state management](https://ably.com/docs/connect/states) -- [Error handling best practices](https://ably.com/docs/connect/failures) +- [Error codes documentation](https://ably.com/docs/errors/codes) +- [Connection recovery](https://ably.com/docs/connect/states#connection-recovery) + +## Related Errors + +• **[80000 - Connection Failed](https://help.ably.io/error/80000)** + General connection failure that may occur alongside cancellations + +• **[80002 - Connection Suspended](https://help.ably.io/error/80002)** + Connection moved to suspended state after extended disconnection + +• **[50003 - Request Timeout](https://help.ably.io/error/50003)** + Server-side timeout as opposed to client-side cancellation ## Need Further Help? @@ -113,36 +140,41 @@ Our team will help you resolve this issue as quickly as possible. - + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/50001-internal-channel-error.mdx b/src/pages/docs/platform/errors/codes/50001-internal-channel-error.mdx index 83f155fcca..88de27e256 100644 --- a/src/pages/docs/platform/errors/codes/50001-internal-channel-error.mdx +++ b/src/pages/docs/platform/errors/codes/50001-internal-channel-error.mdx @@ -1,13 +1,13 @@ - + - + # Error 50001: Internal Channel Error @@ -41,19 +41,19 @@ You may see one of these messages: - Publishing messages faster than the server can process - Too many pending messages awaiting acknowledgment - Lack of backpressure handling in your application - + 2. **Channel not responding** (30% of cases) - Channel process temporarily unavailable - Communication timeout between client and channel - Network interruption during message acknowledgment - + 3. **Internal channel state issues** (10% of cases) - Unexpected channel state during operation - Temporary server-side processing error - Recovery process in progress - + ## Resolution Steps @@ -70,7 +70,8 @@ You may see one of these messages: ``` - Reduce your message publishing rate - Consider batching multiple small messages into fewer larger ones - + + 3. **For channel not responding errors** - Detach and reattach the channel: @@ -80,17 +81,19 @@ You may see one of these messages: ``` - Verify your connection state is `connected` - Check network connectivity - + + 4. **If errors persist beyond 2 minutes** - Check https://status.ably.com for service status - Note the exact error message and timestamp - Review recent changes to your implementation - + - Monitor if the issue affects specific channels or all channels + ## Automatic Handling -Ably SDKs automatically retry server errors with exponential backoff. The SDK will: +Ably SDKs automatically retry server errors with appropriate backoff strategies. The SDK will: - Retry the operation with increasing delays - Preserve message order during retries - Notify you if the error becomes permanent @@ -103,7 +106,8 @@ Manual retry is not needed for transient 50001 errors. - **Use publish callbacks**: Wait for acknowledgment before sending high volumes - **Monitor channel health**: Subscribe to connection state changes - **Batch messages**: Combine multiple small messages when possible - +- **Set appropriate rate limits**: Design your application with sustainable message rates + ## Performance Impact @@ -120,7 +124,21 @@ The connection remains active, and other channels continue to function normally. - [Connection state management](https://ably.com/docs/realtime/connection) - [Publishing messages](https://ably.com/docs/channels/messages#publish) - [Chat API documentation](https://ably.com/docs/chat) (if using Ably Chat) - + + +## Related Errors + +• **[50000 - Internal Server Error](https://help.ably.io/error/50000)** + General server error that may indicate broader system issues + +• **[50002 - Internal Connection Error](https://help.ably.io/error/50002)** + Connection-level error that may affect channel operations + +• **[50003 - Timeout Error](https://help.ably.io/error/50003)** + Server timeout that may occur alongside channel errors + +• **[80002 - Connection Suspended](https://help.ably.io/error/80002)** + Connection state that prevents channel operations after prolonged disconnection ## Need Further Help? @@ -141,16 +159,16 @@ Our team will help you resolve this issue as quickly as possible. - + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/50002-internal-connection-error.mdx b/src/pages/docs/platform/errors/codes/50002-internal-connection-error.mdx index 073344c27d..d18e388592 100644 --- a/src/pages/docs/platform/errors/codes/50002-internal-connection-error.mdx +++ b/src/pages/docs/platform/errors/codes/50002-internal-connection-error.mdx @@ -1,13 +1,13 @@ - + - + # Error 50002: Internal connection error @@ -38,68 +38,107 @@ You may see one of these messages: ## Common Causes - + 1. **DNS resolution failures** (70% of cases) - Unable to resolve Ably hostnames - Incorrect fallback host configuration - DNS server issues + - Custom domain typos (e.g., `jago-a-fallback.ably-realtime.com` instead of valid domain) 2. **Network routing problems** (20% of cases) - No route to host - Firewall blocking connections - Network connectivity issues + - Connection attempts to removed backends 3. **Internal state issues** (10% of cases) - Corrupted connection state - Unexpected protocol violations - Backend resource temporarily unavailable + - Router logic errors during infrastructure changes ## Resolution Steps - + 1. **For transient errors (most cases)** - Ably SDKs automatically retry with exponential backoff - No action required unless persistent for more than 2 minutes - + 2. **Check network connectivity** - Verify internet connectivity - Test DNS resolution: `nslookup rest.ably.io` - Confirm no firewall blocks to Ably endpoints + - Test specific fallback domains if configured 3. **Review fallback host configuration (if customized)** - - - Remove explicit fallbackHosts if not needed - - Verify all custom fallback hosts are valid + + - Remove explicit fallbackHosts if not needed - let SDK use defaults + - Verify all custom fallback hosts are valid and resolvable - Ensure correct domain syntax without typos + - Default fallback hosts work well for most use cases 4. **For persistent errors** - Check https://status.ably.com for service issues - Update to the latest SDK version - - Note the full error message and request ID + - Note the full error message including any host names + - Capture the request ID for support reference ## Automatic Handling Ably SDKs automatically retry this error with exponential backoff since it has HTTP status 500. The SDK will: - Attempt reconnection with increasing delays -- Try fallback hosts if configured -- Eventually enter a suspended state if unable to reconnect +- Try fallback hosts automatically (defaults or configured) +- Eventually enter a suspended state if unable to reconnect after 2 minutes + +## SDK-Specific Behavior + + + +### JavaScript SDK +- Returns this error for unknown connection issues +- Also used for internal channel errors +- Part of automatic retry category +- Called from `unknownConnectionErr()` and `unknownChannelErr()` functions + +### Java/Android SDK +- Specifically triggered by `UnknownHostException` and `NoRouteToHostException` +- Preserves original exception message for debugging +- Common in mobile apps with network transitions +- Falls back to error 50000 for other IOException types ## Prevention - Use default Ably configuration unless specific requirements exist +- If using custom fallback hosts, thoroughly test DNS resolution - Keep SDKs updated to latest versions - Monitor connection state in your application - Implement connection state change listeners for visibility +- For mobile applications, handle network transitions gracefully ## Related Resources -- [Connection state management](https://ably.com/docs/realtime/connection) -- [Connection recovery documentation](https://ably.com/docs/connect/states) -- [Fallback host configuration](https://ably.com/docs/best-practice/fallback-hosts) - [Ably system status](https://status.ably.com) +- [Ably support](https://ably.com/support) + +## Related Errors + +• **[50000 - Internal Server Error](https://help.ably.io/error/50000)** + General server error that may occur alongside connection issues + +• **[50003 - Internal Timeout Error](https://help.ably.io/error/50003)** + Timeout variant that can occur during connection establishment + +• **[80000 - Connection Failed](https://help.ably.io/error/80000)** + Terminal connection failure after exhausting retries + +• **[80002 - Connection Suspended](https://help.ably.io/error/80002)** + Connection enters suspended state after persistent failures + +• **[80003 - Connection Disconnected](https://help.ably.io/error/80003)** + Connection temporarily disconnected but attempting to reconnect ## Need Further Help? @@ -121,32 +160,50 @@ Our team will help you resolve this issue as quickly as possible. + + + + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/50003-timeout-error.mdx b/src/pages/docs/platform/errors/codes/50003-timeout-error.mdx index 8ae6741a8a..454bfef4f3 100644 --- a/src/pages/docs/platform/errors/codes/50003-timeout-error.mdx +++ b/src/pages/docs/platform/errors/codes/50003-timeout-error.mdx @@ -1,13 +1,13 @@ - + - + # Error 50003: Timeout error @@ -24,136 +24,182 @@ An operation timed out before completing, typically due to network issues, tempo ## Quick Fix -- For REST SDK users: No action needed - automatic retry is handled -- For Realtime SDK users: Implement application-level retry logic -- Check [Ably status page](https://status.ably.com) if persistent -- Consider increasing timeout values in SDK configuration +- **REST SDK users**: No action needed - automatic retry is handled +- **Realtime SDK users**: Implement application-level retry logic (SDK does NOT auto-retry by design) +- Check [Ably status page](https://status.ably.com) if timeouts persist beyond 2 minutes +- Consider increasing timeout values in SDK configuration for high-latency networks ## Error Messages You may see one of these messages: -- "Message send timeout expired" +- "Message send timeout expired" - Message not acknowledged within 30 seconds - "Timeout for trying fallback hosts retries. Total elapsed time exceeded the [timeout]ms limit" -- "timed out before attaching channel" -- "timed out before detaching channel" -- "Ping request cancelled due to request timeout" -- "Timeout waiting for ping response" -- "Connection cancelled due to request timeout" -- "Ping failed as connection has changed state to {state}" -- "cURL error: [specific error message]" -- "network timeout" +- "timed out before attaching channel" - Channel attach operation timeout +- "timed out before detaching channel" - Channel detach operation timeout +- "Ping request cancelled due to request timeout" - Keep-alive ping timeout +- "Timeout waiting for ping response" - No ping response received +- "Connection cancelled due to request timeout" - Connection establishment timeout +- "Ping failed as connection has changed state to {state}" - Connection state changed during ping +- "cURL error: [specific error message]" - Network-level timeout (PHP SDK) +- "network timeout" - Generic network operation timeout +- "write: connection timed out" - Connection write operation timeout +- "network is unreachable" - Network connectivity issue The `{state}` shows the current connection state, and `[timeout]` shows the configured timeout duration in milliseconds. ## Common Causes 1. **Network connectivity issues** (40% of cases) - - - High network latency - - Packet loss - - Intermittent connectivity - - Network unreachability + + - High network latency exceeding timeout thresholds + - Packet loss causing retransmission delays + - Intermittent connectivity or network flapping + - Network unreachability or routing issues + - Firewall or proxy interference with WebSocket connections 2. **Message acknowledgment timeout** (30% of cases) - - - Messages not acknowledged within 30 seconds - - RPC communication failures between services - - Server processing delays + + - Messages not acknowledged by server within 30 seconds + - RPC communication failures between Ably services + - Server processing delays during high load + - Presence ENTER messages failing to receive ACK 3. **Channel operation timeout** (15% of cases) - - - Channel attach taking too long - - Channel detach not completing - - State transition delays + + - Channel attach taking longer than `realtimeRequestTimeout` + - Channel detach not completing within timeout period + - State transition delays in channel lifecycle + - Channel release failures (as seen with PSIServices incident) 4. **Configuration issues** (10% of cases) - + - Timeout values set too low for network conditions - - Insufficient `realtimeRequestTimeout` setting - - Low `httpMaxRetryDuration` for fallback hosts + - Insufficient `realtimeRequestTimeout` setting (default 10 seconds) + - Low `httpMaxRetryDuration` for fallback host attempts + - Misconfigured load balancers or proxies 5. **Temporary service issues** (5% of cases) - - - Service temporarily unavailable (503) - - High server load - - Infrastructure problems + + - Service temporarily unavailable (HTTP 503) + - High server load during peak periods + - Infrastructure problems or regional issues + - Database connection timeouts (Cassandra) ## Resolution Steps -1. **Check SDK type and retry behavior** - - - **REST SDK**: Automatically retries - no action needed - - **Realtime SDK**: Does NOT auto-retry to avoid duplicate messages - implement application-level retry +1. **Understand critical SDK behavior difference** + + - **REST SDK**: Automatically retries with exponential backoff - no action needed + - **Realtime SDK**: Does NOT auto-retry (by design to prevent duplicate messages) + - This is a fundamental architectural decision - not a bug 2. **For Realtime SDK users - implement retry logic** ```javascript // Handle timeout errors with application-level retry - channel.publish('message', data, (err) => { - if (err && err.code === 50003) { - // Implement your retry logic here - setTimeout(() => { - channel.publish('message', data); - }, 1000); // Start with 1 second delay + let retryCount = 0; + const maxRetries = 3; + + async function publishWithRetry(channel, name, data) { + try { + await channel.publish(name, data); + } catch (err) { + if (err.code === 50003 && retryCount < maxRetries) { + retryCount++; + const delay = Math.min(1000 * Math.pow(2, retryCount), 10000); + await new Promise(resolve => setTimeout(resolve, delay)); + return publishWithRetry(channel, name, data); + } + throw err; } - }); + } ``` - + -3. **Increase timeout configuration** +3. **Increase timeout configuration for your network conditions** ```javascript const ably = new Ably.Realtime({ key: 'your-api-key', - realtimeRequestTimeout: 45000, // Increase from default 10s to 45s - httpMaxRetryDuration: 30000 // Increase HTTP retry duration + realtimeRequestTimeout: 45000, // Increase from default 10s to 45s + httpMaxRetryDuration: 30000, // Increase HTTP retry duration + disconnectedRetryTimeout: 15000 // Adjust disconnected retry timeout }); ``` - + -4. **Monitor for patterns** - - Check if timeouts occur at specific times +4. **Monitor for patterns to identify root cause** + - Check if timeouts occur at specific times (load patterns) - Identify if specific operations consistently timeout - Review network path between client and Ably + - Look for correlation with other error codes (40000, 50000) + - Check if issue is regional or global 5. **For persistent issues (>2 minutes)** - Check https://status.ably.com for service status - Review recent infrastructure or code changes - Consider regional connectivity issues + - Note request IDs from error messages for support + +6. **For load testing scenarios** + + - Increase timeout limits significantly for load tests + - Consider using REST SDK for high-volume publishing + - Implement batching to reduce individual requests + - Monitor RPC communication metrics if available ## Automatic Handling - -- **REST SDK**: Automatically retries with exponential backoff -- **Realtime SDK**: Does NOT automatically retry (by design to prevent duplicate messages) -- **Connection recovery**: SDK attempts reconnection for connection timeouts -- **Fallback hosts**: Automatically tried when primary host times out (ably-js) + +- **REST SDK**: Automatically retries with exponential backoff up to `httpMaxRetryDuration` +- **Realtime SDK**: Does NOT automatically retry publish operations (prevents duplicates) +- **Connection recovery**: SDK attempts automatic reconnection for connection timeouts +- **Fallback hosts**: Automatically tried when primary host times out (ably-js and other SDKs) +- **Channel state**: Transitions to SUSPENDED after persistent timeouts ## Prevention -- Set appropriate timeout values based on your network conditions -- Monitor timeout patterns to identify infrastructure issues +- Set appropriate timeout values based on your network conditions and use case +- Monitor timeout patterns to identify infrastructure issues early - Use REST SDK for critical message publishing that requires automatic retry -- Implement application-level retry logic when using Realtime SDK -- Consider network optimization and regional deployment +- Implement robust application-level retry logic when using Realtime SDK +- Consider network optimization and regional deployment strategies +- For load testing, pre-configure higher timeout values +- Implement circuit breakers for persistent timeout scenarios ## Performance Impact -This error indicates temporary delays but doesn't affect: -- Other channel operations +This error indicates temporary delays but doesn't immediately affect: +- Other channel operations on different channels - Existing subscriptions (unless connection timeout) - Messages already queued for delivery +- Other connections or sessions Connection timeouts may cause: -- Brief message delivery delays -- Presence member updates -- Need to re-establish subscriptions +- Brief message delivery delays during reconnection +- Presence member list updates +- Need to re-establish subscriptions if connection enters failed state +- Potential message loss if not using persistent history + +## Related Errors + +• **[80014 - Connection Timeout](https://help.ably.io/error/80014)** + Connection-specific timeout during establishment or keep-alive operations + +• **[80000 - Connection Failed](https://help.ably.io/error/80000)** + May follow persistent 50003 timeouts when connection cannot be recovered + +• **[50000 - Internal Server Error](https://help.ably.io/error/50000)** + General server error that may accompany timeout issues during incidents + +• **[40000 - Bad Request](https://help.ably.io/error/40000)** + Often seen alongside 50003 during network issues (as per 17Live incident) ## Related Resources -- [Connection state management](https://ably.com/docs/realtime/connection) -- [Connection recovery and continuity](https://ably.com/docs/connect/states) -- [Timeout configuration](https://ably.com/docs/api/realtime-sdk#client-options) +- [Connection state management](https://ably.com/docs/connect) +- [Connection recovery and continuity](https://ably.com/docs/connect) +- [Client options and timeout configuration](https://ably.com/docs/api/realtime-sdk) +- [REST vs Realtime SDK comparison](https://ably.com/docs/sdks) - [Ably status page](https://status.ably.com) -- Related errors: [80014](./80014-connection-timeout.md) (connection-specific timeout), [50000](./50000-internal-error.md) (general server error) ## Need Further Help? @@ -167,6 +213,8 @@ When contacting support, please provide: - Steps to reproduce the issue - Any relevant code snippets (without sensitive credentials) - The SDK and version you're using +- Request IDs from error messages if available +- Whether you're using REST or Realtime SDK Our team will help you resolve this issue as quickly as possible. @@ -175,38 +223,56 @@ Our team will help you resolve this issue as quickly as possible. + + + + + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/50004-service-unavailable-capacity-limit.mdx b/src/pages/docs/platform/errors/codes/50004-service-unavailable-capacity-limit.mdx index cbc9568181..5f2f7fb117 100644 --- a/src/pages/docs/platform/errors/codes/50004-service-unavailable-capacity-limit.mdx +++ b/src/pages/docs/platform/errors/codes/50004-service-unavailable-capacity-limit.mdx @@ -1,13 +1,13 @@ - + - + # Error 50004: Service Unavailable (Capacity Limit) @@ -27,6 +27,7 @@ Ably's servers temporarily cannot process your request due to capacity limits or - Wait and retry with exponential backoff starting at 1-2 seconds - Check [Ably's status page](https://status.ably.com) for any ongoing issues - Spread your requests over time if sending high volumes +- Review batch publish operations if using REST API ## Error Messages @@ -40,30 +41,34 @@ You may see one of these messages: ## Common Causes 1. **Server capacity limits reached** (80% of cases) - + - High traffic volume exceeding instance capacity - Server entering protective "siege mode" during overload - Instance-level rate limiting triggered + - Batch publish operations during peak times 2. **Connection rate limiting** (10% of cases) - + - Too many new connections being established simultaneously - Connection burst exceeding server limits + - Test infrastructure creating excessive connections 3. **Message publish rate limiting** (5% of cases) - + - Publishing messages too rapidly - - Batch publish operations exceeding rate limits + - REST batch publish operations exceeding rate limits + - High-volume enterprise customers hitting publish limits 4. **Gateway timeouts** (5% of cases) - + - Upstream service timeout (HTTP 504) - Network or infrastructure delays + - Backend service communication issues ## Resolution Steps 1. **Implement exponential backoff retry** - + - Start with a 1-2 second delay - Double the delay for each retry (2s, 4s, 8s, 16s...) - Add random jitter to prevent thundering herd @@ -74,17 +79,27 @@ You may see one of these messages: - Visit [Ably's status page](https://status.ably.com) for any reported issues - Check if the issue is widespread or isolated + - Monitor for siege mode indicators 3. **Optimize request patterns** - + - Spread high-volume operations across time periods - Avoid burst traffic patterns - Consider implementing client-side rate limiting - Use batch operations judiciously during peak times + - Review REST batch publish implementations -4. **For persistent issues** - +4. **For batch publish operations** + + - Monitor for increased 503 errors with batch publish + - Consider splitting large batches into smaller operations + - Implement gradual ramp-up for batch operations + - Use server-side batching where appropriate + +5. **For persistent issues** + - Review your usage patterns for optimization opportunities + - Check instance rate counters if available - Consider upgrading your plan for higher limits - Contact support with request patterns and timing details @@ -101,19 +116,31 @@ You don't need to implement your own retry logic unless you're using the REST AP ## Prevention - **Rate limiting awareness**: Monitor your request rates and stay within documented limits - + - **Load distribution**: Spread high-volume operations across time - **Connection pooling**: Reuse connections instead of creating new ones - **Batch wisely**: Use batch operations but be mindful of size and frequency - **Monitor patterns**: Track 50004 errors as early capacity warning indicators +- **Test infrastructure**: Implement rate limiting in test suites to avoid overload ## Related Resources -- [Ably Rate Limits Documentation](https://ably.com/docs/general/limits) -- [Connection State Management](https://ably.com/docs/realtime/connection) -- [Batch Publishing Guide](https://ably.com/docs/rest/messages#batch) +- [Ably Rate Limits Documentation](https://ably.com/docs/pricing/limits) +- [Connection State Management](https://ably.com/docs/connect/states) +- [Message Batching Guide](https://ably.com/docs/messages/batch) - [Status Page](https://status.ably.com) +## Related Errors + +• **[40000 - Bad Request](https://help.ably.io/error/40000)** + May occur when attempting operations in suspended state after capacity issues + +• **[42910 - Rate Limit Exceeded](https://help.ably.io/error/42910)** + Similar rate limiting but with different retry requirements + +• **[50003 - Internal Server Error](https://help.ably.io/error/50003)** + Related server-side error that may occur during high load + ## Need Further Help? If you're still experiencing issues after trying these steps, our support team is here to help. @@ -126,6 +153,7 @@ When contacting support, please provide: - Steps to reproduce the issue - Any relevant code snippets (without sensitive credentials) - The SDK and version you're using +- Details about batch operations if applicable Our team will help you resolve this issue as quickly as possible. @@ -133,34 +161,42 @@ Our team will help you resolve this issue as quickly as possible. - + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/50005-service-lockdown.mdx b/src/pages/docs/platform/errors/codes/50005-service-lockdown.mdx index 770abdf889..6c46220731 100644 --- a/src/pages/docs/platform/errors/codes/50005-service-lockdown.mdx +++ b/src/pages/docs/platform/errors/codes/50005-service-lockdown.mdx @@ -1,20 +1,20 @@ - + - + # Error 50005: Service in lockdown ## What Happened? -Ably has temporarily placed one or more services in emergency lockdown mode to protect infrastructure during a critical incident. +Ably has temporarily placed one or more services in emergency lockdown mode to protect critical infrastructure during an operational incident. ## Quick Reference @@ -26,7 +26,7 @@ Ably has temporarily placed one or more services in emergency lockdown mode to p - Check [Ably status page](https://status.ably.com) for active incidents - Wait for incident resolution before retrying -- Consider fallback options if time-critical +- Consider implementing graceful degradation for time-critical operations ## Error Messages @@ -34,57 +34,86 @@ You may see one of these messages: - "Service Unavailable (service in lockdown)" - "Service Unavailable (unable to modify Push data; service in lockdown)" +The specific message indicates which service is affected. + ## Common Causes 1. **Active Infrastructure Incident** (90% of cases) - Operators have activated emergency lockdown - Protects services during critical issues - - Prevents cascading failures - + - Prevents cascading failures across the platform + 2. **Service-Specific Protection** (10% of cases) - - Database infrastructure protection (Cassandra) - - Authentication service protection (token requests) - - Push notification service protection - + - **Database infrastructure** (Cassandra): Protects data consistency during database issues + - **Authentication service**: Safeguards token generation during auth service stress + - **Push notification service**: Prevents corruption of push registration data + ## Resolution Steps -1. **Check Ably Status** +1. **Check Ably Status Immediately** - Visit https://status.ably.com - - Look for active incidents or maintenance - - Subscribe to incident updates - + - Look for active incidents or maintenance notices + - Subscribe to incident updates for real-time notifications + -2. **Monitor and Wait** - - This is an operational decision, not a transient error +2. **Understand the Lockdown Nature** + - This is an operational circuit breaker, not a transient error + - Lockdown is manually controlled by Ably operators - Service will automatically recover when lockdown is lifted - - Typical resolution time varies by incident severity - + - Resolution time depends on incident severity + 3. **Implement Graceful Degradation** - - Queue non-critical operations for later + - Queue non-critical operations for later processing - Show appropriate user messaging about temporary unavailability - - Avoid aggressive retry loops that won't succeed - + - Avoid aggressive retry loops that won't succeed during lockdown + - Consider fallback strategies for critical operations + + +4. **Monitor Recovery** + - Keep checking the status page for resolution updates + - Test connectivity after incident is marked resolved + - Resume normal operations gradually to avoid overwhelming recovered services ## Automatic Handling -Ably SDKs will not automatically retry this error indefinitely as it indicates an operational lockdown that requires manual intervention to resolve. The SDK may attempt limited retries but will ultimately fail if the lockdown persists. - +Ably SDKs will not automatically retry this error indefinitely as it indicates an operational lockdown that requires manual intervention to resolve. The SDK may attempt limited retries with exponential backoff but will ultimately fail if the lockdown persists. + ## Prevention -This error cannot be prevented by client applications as it represents an infrastructure protection mechanism activated by Ably operators during emergencies. Focus on: +This error cannot be prevented by client applications as it represents an infrastructure protection mechanism activated by Ably operators during emergencies. Focus instead on: - Building resilient applications that handle temporary service unavailability - Implementing proper error handling and user feedback - Having fallback strategies for critical operations +- Monitoring Ably status page proactively for maintenance windows + +## Technical Context + +The lockdown mechanism is controlled by Ably's `emergencyServiceLockdown` configuration and can affect specific services independently: +- Cassandra database operations may continue while push services are locked +- Token generation may be blocked while message publishing continues +- Each service has independent lockdown controls for granular incident response + ## Related Resources - [Ably Status Page](https://status.ably.com) -- [Connection states and recovery](https://ably.com/docs/realtime/connection#connection-state-recovery) -- [Error handling best practices](https://ably.com/docs/best-practice#error-handling) +- [Connection states and recovery](https://ably.com/docs/connect/states) +- [Error codes documentation](https://ably.com/docs/errors/codes) + +## Related Errors + +• **[50000 - Internal Server Error](https://help.ably.io/error/50000)** + General server errors that may precede or follow lockdown conditions + +• **[50003 - Timeout Error](https://help.ably.io/error/50003)** + Request timeouts that might occur during service degradation + +• **[80002 - Connection Suspended](https://help.ably.io/error/80002)** + Connection state when unable to maintain connectivity during incidents ## Need Further Help? @@ -105,39 +134,53 @@ Our team will help you resolve this issue as quickly as possible. - + + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/50010-internal-server-error.mdx b/src/pages/docs/platform/errors/codes/50010-internal-server-error.mdx index 7d9cf39d75..d6d6002c97 100644 --- a/src/pages/docs/platform/errors/codes/50010-internal-server-error.mdx +++ b/src/pages/docs/platform/errors/codes/50010-internal-server-error.mdx @@ -1,20 +1,20 @@ - + - + # Error 50010: Internal server error ## What Happened -Ably's infrastructure encountered an internal error while processing your request. This typically occurs when edge proxy services or resource allocation systems experience unexpected issues. +Ably's infrastructure encountered an internal error while processing your request, either in the edge proxy service or when allocating resources in our distributed cluster. ## Quick Reference @@ -36,44 +36,50 @@ You may see one of these messages: - "Client application:{id} unavailable timer expired" - "Client channel:{id} unavailable timer expired" - "Client account:{id} unavailable timer expired" +- "{ResourceType}:{id} Unable to place instance compatible with constraints" ## Common Causes 1. **Edge proxy issues** (60% of cases) - + - CloudFront encounters unrecognized error status - Network routing problems between edge and origin - Temporary edge server overload 2. **Resource allocation failures** (30% of cases) - + - Cluster cannot find nodes matching placement constraints - Resource initialization timeout exceeded - Insufficient capacity in specific regions -3. **Infrastructure instability** (10% of cases) - +3. **Timer expiration issues** (10% of cases) + + - Resource initialization takes too long - Ring stability problems in distributed system - Core process issues requiring recovery - - Cascading failures during high load ## Resolution Steps 1. **For transient errors (most cases)** + - Ably SDKs automatically retry with exponential backoff - No action required - connection will recover automatically - Monitor your application logs for resolution confirmation 2. **For persistent errors (>2 minutes)** - + - Check https://status.ably.com for any ongoing incidents - Review recent changes to your implementation - - Note the exact error message and timing + - Note the exact error message and timing for support 3. **If affecting critical operations** + - Implement circuit breaker pattern to prevent cascading failures - Consider temporary fallback mechanisms - - Collect diagnostic information for support + - Collect diagnostic information including: + - Full error message with resource IDs + - Time of occurrence and duration + - Any patterns in affected resources ## Automatic Handling @@ -93,12 +99,30 @@ While this is primarily an infrastructure error, you can minimize impact by: - Monitoring connection state changes in your application - Setting appropriate timeout values for critical operations +## Performance Impact + +This error can cause: +- Temporary message delivery delays +- Channel attachment failures until recovery +- Connection state transitions to `disconnected` or `suspended` +- Potential message queue buildup during outage + ## Related Resources -- [Connection state recovery](https://ably.com/docs/realtime/connection#connection-state-recovery) -- [Error handling best practices](https://ably.com/docs/best-practice#error-handling) +- [Connection state recovery](https://ably.com/docs/connect/states) +- [Connection states documentation](https://ably.com/docs/connect) - [Ably status page](https://status.ably.com) -- Related errors: [50000](./50000-internal-error.md), [50003](./50003-timeout-error.md) + +## Related Errors + +• **[50000 - Internal Error](https://help.ably.io/error/50000)** + General internal server error without specific infrastructure context + +• **[50003 - Timeout Error](https://help.ably.io/error/50003)** + Request timeout that may occur alongside resource allocation issues + +• **[80000 - Connection Failed](https://help.ably.io/error/80000)** + May result from persistent 50010 errors preventing connection establishment ## Need Further Help? @@ -119,41 +143,45 @@ Our team will help you resolve this issue as quickly as possible. - + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/50210-bad-gateway.mdx b/src/pages/docs/platform/errors/codes/50210-bad-gateway.mdx index a437ffc6b3..6c3450da03 100644 --- a/src/pages/docs/platform/errors/codes/50210-bad-gateway.mdx +++ b/src/pages/docs/platform/errors/codes/50210-bad-gateway.mdx @@ -1,13 +1,13 @@ - + - + # Error 50210: Bad Gateway @@ -25,70 +25,135 @@ Ably's edge proxy service received an invalid response from the upstream Ably pl ## Quick Fix - No immediate action required - Ably SDKs handle retry automatically -- Check [Ably status page](https://status.ably.com) if persistent -- Implement exponential backoff if using REST API directly +- Check [Ably status page](https://status.ably.com) if error persists beyond 2 minutes +- For direct REST API usage, implement exponential backoff retry logic ## Error Messages You may see this message: - "Ably's edge proxy service received an invalid (bad gateway) response from the Ably platform" +This error appears when CloudFront edge proxy receives HTTP 502 status from upstream Ably servers. + ## Common Causes - + 1. **Upstream platform issues** (Most common) - Ably platform servers returning invalid responses during incidents - Service degradation during high load periods + - Temporary infrastructure disruptions -2. **Transient network issues** +2. **Transient network issues** (Common) - Temporary connectivity problems between CloudFront and Ably platform - Network routing issues between edge locations and core infrastructure + - Brief interruptions in inter-datacenter connectivity + +3. **Regional outages** (Less common) + - Issues affecting specific CloudFront edge locations + - Localized infrastructure problems in certain geographic regions + - Edge location-specific connectivity issues -3. **Regional outages** - - Affecting specific CloudFront edge locations - - Localized infrastructure problems +4. **Batch processing overload** (For high-volume operations) + + - Large notification batches overwhelming upstream capacity + - Concurrent batch operations during peak times ## Resolution Steps 1. **For transient errors (most cases)** - + - Ably SDKs automatically retry with appropriate backoff - No action required unless error persists for more than 2 minutes + - Monitor your application logs for error frequency 2. **For persistent errors (>2 minutes)** - - Check https://status.ably.com for platform incidents - - Review recent changes to your implementation - - Note the time and frequency of errors for support + - Check https://status.ably.com for active platform incidents + - Review recent changes to your implementation or traffic patterns + - Note the exact time and frequency of errors for support reference + - Consider temporary traffic reduction if possible 3. **If using REST API directly** - - - Implement exponential backoff retry logic - - Start with 1 second delay, doubling up to 32 seconds - - Include jitter to avoid thundering herd effect + + ```javascript + // Implement exponential backoff + async function retryWithBackoff(fn, maxRetries = 5) { + let delay = 1000; // Start with 1 second + for (let i = 0; i < maxRetries; i++) { + try { + return await fn(); + } catch (error) { + if (error.code !== 50210 || i === maxRetries - 1) throw error; + // Add jitter to avoid thundering herd + const jitter = Math.random() * 1000; + await new Promise(resolve => setTimeout(resolve, delay + jitter)); + delay = Math.min(delay * 2, 32000); // Cap at 32 seconds + } + } + } + ``` + 4. **For batch operations** - + - Keep track of failed batches for manual replay if needed - Consider implementing circuit breaker patterns for repeated failures - - Monitor for patterns (time of day, specific operations) + - Monitor for patterns (specific time windows, operation types) + - Split large batches into smaller chunks to reduce impact + +5. **Verify SDK error handling** + + - Ensure you're using a current SDK version + - Some older SDKs incorrectly wrap 50210 in error 400, preventing automatic retry + - Update to latest SDK version if experiencing retry issues ## Automatic Handling - -Ably SDKs automatically retry server errors with exponential backoff. However, some older SDK versions may incorrectly wrap this in a 400 error, preventing automatic retry. Ensure you're using a current SDK version for proper error handling. + +Ably SDKs automatically retry server errors with exponential backoff. The SDK will: +- Retry with increasing delays (1s, 2s, 4s, 8s, etc.) +- Add jitter to prevent synchronized retry storms +- Eventually enter suspended state if errors persist + +**Important**: Some older SDK versions may incorrectly handle this error by wrapping it in a 400 client error, which prevents automatic retry. Ensure you're using a current SDK version for proper error handling. ## Prevention -- Use current SDK versions for proper error handling -- Implement monitoring for 50210 errors to detect patterns -- Consider geographic distribution of requests to avoid single edge location issues -- Keep batch sizes reasonable to minimize impact of failures +- **Use current SDK versions** for proper automatic error handling +- **Implement monitoring** for 50210 errors to detect patterns early +- **Geographic distribution**: Spread requests across multiple regions to avoid single edge location issues +- **Batch optimization**: Keep batch sizes reasonable (under 100 messages) to minimize failure impact +- **Circuit breaker patterns**: Implement circuit breakers for high-volume operations +- **Error tracking**: Log error timestamps to identify patterns (e.g., specific times of day) + +## Performance Impact + +This error can affect: +- **Message delivery latency** during retry cycles +- **Batch processing completion** for notification systems +- **Real-time data flow** until connection recovers +- **Client connection state** if errors persist + +The connection will remain in attempting/suspended states during persistent errors, with automatic recovery once the upstream issue resolves. ## Related Resources - [Ably Status Page](https://status.ably.com) - Check for platform incidents -- [Connection State Management](https://ably.com/docs/realtime/connection) - Understanding connection recovery -- Related errors: [50003](./50003-timeout.md) (Timeout), [50310](./50310-service-unavailable.md) (Service Unavailable), [50410](./50410-gateway-timeout.md) (Gateway Timeout) +- [Ably Documentation](https://ably.com/docs) - Complete platform documentation +- [Connection State Management](https://ably.com/docs/connect) - Understanding connection recovery + +## Related Errors + +• **[50003 - Timeout Error](https://help.ably.io/error/50003)** + Often occurs alongside 50210 during infrastructure issues affecting request processing + +• **[50310 - Service Unavailable](https://help.ably.io/error/50310)** + Related edge proxy error when upstream returns 503 status instead of 502 + +• **[50410 - Gateway Timeout](https://help.ably.io/error/50410)** + Edge proxy timeout variant when upstream doesn't respond within time limit + +• **[50010 - Internal Server Error](https://help.ably.io/error/50010)** + Generic edge proxy error for unspecified internal failures ## Need Further Help? @@ -109,49 +174,56 @@ Our team will help you resolve this issue as quickly as possible. - + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/50300-service-unavailable.mdx b/src/pages/docs/platform/errors/codes/50300-service-unavailable.mdx index ff4fd2e00f..45eb02cbb0 100644 --- a/src/pages/docs/platform/errors/codes/50300-service-unavailable.mdx +++ b/src/pages/docs/platform/errors/codes/50300-service-unavailable.mdx @@ -1,11 +1,11 @@ - + @@ -29,7 +29,7 @@ A required service within Ably's infrastructure is temporarily unavailable, prev You may see one of these messages: - "Service Unavailable" -- "failed to make request: [details]" +- "failed to make request: %v" (where %v contains specific error details) - "Active Traffic Management: traffic is being temporarily redirected to a backup service" - "Ably's routing layer was unable to service this request" @@ -39,26 +39,26 @@ You may see one of these messages: - Service maintenance or deployment - Routing layer temporarily unavailable - Infrastructure capacity adjustments - + 2. **Moderation service unavailable** (25% of cases) - External moderation service unreachable - Network connectivity issues between services - Moderation service experiencing downtime - + 3. **Active Traffic Management** (15% of cases) - Emergency traffic redirection to backup clusters - Planned infrastructure migration - Regional failover scenarios - + ## Resolution Steps 1. **For transient errors (most cases)** - Ably SDKs automatically retry with exponential backoff - No action required unless persistent for more than 2 minutes - + 2. **For persistent errors (>2 minutes)** - Check https://status.ably.com for any ongoing incidents @@ -66,18 +66,18 @@ You may see one of these messages: - `X-Ably-Serverid`: Identifies which router responded - May include alternate `realtimeHost` or `restHost` during traffic management - Note any custom error messages that provide specific guidance - + 3. **If using Chat with moderation enabled** - The error may indicate moderation service issues - Messages will be queued and retried automatically - Consider temporarily disabling moderation if time-critical - + 4. **Monitor and verify recovery** - Errors should resolve within minutes - If persistent beyond 5 minutes, note the request ID and server ID from headers - + ## Automatic Handling Ably SDKs automatically retry 503 errors with exponential backoff. The SDK will: @@ -85,7 +85,7 @@ Ably SDKs automatically retry 503 errors with exponential backoff. The SDK will: - Continue retrying for up to 2 minutes - Fall back to alternate endpoints if provided - Queue messages during temporary disconnections - + ## Prevention @@ -95,11 +95,21 @@ While 503 errors are typically infrastructure-related and outside your control: - Monitor for patterns in your application logs - Subscribe to [Ably status updates](https://status.ably.com) for proactive notifications +## Related Errors + +• **[50000 - Internal Server Error](https://help.ably.io/error/50000)** + General server error that may occur alongside service unavailability issues + +• **[50305 - Routing Error](https://help.ably.io/error/50305)** + Specific routing layer failure often seen with 50300 during infrastructure issues + +• **[50001 - Operation Timeout](https://help.ably.io/error/50001)** + May occur when services are slow to respond rather than completely unavailable + ## Related Resources -- [Connection state recovery](https://ably.com/docs/connect/states) -- [Error handling best practices](https://ably.com/docs/best-practice#error-handling) +- [Ably documentation](https://ably.com/docs) - [Ably system status](https://status.ably.com) -- Related errors: [50000](./50000-internal-error.md), [50305](./50305-routing-error.md) +- [Error handling best practices](https://ably.com/docs) ## Need Further Help? @@ -120,11 +130,11 @@ Our team will help you resolve this issue as quickly as possible. - + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/50310-edge-service-unavailable.mdx b/src/pages/docs/platform/errors/codes/50310-edge-service-unavailable.mdx index 81dfd42222..4bc3f75ae7 100644 --- a/src/pages/docs/platform/errors/codes/50310-edge-service-unavailable.mdx +++ b/src/pages/docs/platform/errors/codes/50310-edge-service-unavailable.mdx @@ -1,20 +1,20 @@ - + - + # Error 50310: Edge service unavailable ## What Happened -Ably's edge proxy service received a service unavailable response from the Ably platform backend. +Ably's CloudFront edge proxy service received a service unavailable response (HTTP 503) from the Ably platform backend. ## Quick Reference @@ -26,7 +26,7 @@ Ably's edge proxy service received a service unavailable response from the Ably - No immediate action required - Ably SDKs handle retry automatically - Check [Ably status page](https://status.ably.com) if persistent -- The platform will typically recover within minutes +- If experiencing high-volume operations, consider implementing rate limiting ## Error Messages @@ -35,82 +35,116 @@ You may see this message: ## Common Causes -1. **Temporary platform unavailability** (most common) - - Brief service disruption - - Platform overload during traffic spikes - - Automatic recovery expected - - -2. **Backend service issues** - - Core Ably services experiencing availability problems - - Usually resolved quickly by automatic failover - - -3. **Network communication issues** - - Temporary network problems between CloudFront edge and Ably platform - - Often transient and self-resolving - - -4. **Planned maintenance** - - Scheduled platform updates - - Check status page for maintenance windows - +1. **Platform overload during traffic spikes** (most common) + - High volume of requests overwhelming the platform + - Often seen during push device registrations or bulk operations + - Example: 10+ new users/second with multiple device registrations each + + +2. **Backend service availability issues** + - Core Ably services experiencing problems + - Router failing to forward requests via netmap + - Connection timeout issues in frontdoor services + + +3. **Network communication problems** + - Issues between CloudFront edge and Ably platform + - Context cancellation errors in frontend layers + - Serverside ping check warnings (180-240s since last ping) + + +4. **Deployment or maintenance windows** + - Platform updates being rolled out + - Scheduled maintenance activities + - Check status page for announcements + ## Resolution Steps 1. **For transient errors (most cases)** - Ably SDKs automatically retry with appropriate backoff - - No action required unless persistent - - Wait 30-60 seconds for automatic recovery - + - No action required unless persistent beyond 2 minutes + - Monitor connection state for automatic recovery + 2. **For persistent errors (>2 minutes)** - - Check https://status.ably.com for platform status - - Look for any reported incidents or maintenance - - Subscribe to status updates if issue is ongoing - - -3. **If during high-volume operations** - - Consider reducing request rate temporarily - - Implement client-side throttling if pushing large volumes - - Spread load over time if possible - - -4. **Monitor and verify recovery** + - Check https://status.ably.com for platform incidents + - Review recent changes to your implementation + - Note the time and frequency of errors for support + + +3. **For high-volume operations** + - Implement rate limiting on bulk operations + - Spread device registrations over time (avoid 10+ users/second) + - Consider batching requests where possible + - Use connection pooling to reduce overhead + + +4. **Monitor recovery with connection events** ```javascript ably.connection.on('connected', () => { console.log('Successfully reconnected to Ably'); }); - ably.connection.on('failed', (stateChange) => { - console.error('Connection failed:', stateChange.reason); - // Only take action if failure persists + ably.connection.on('disconnected', () => { + console.log('Disconnected - SDK will retry automatically'); + }); + + ably.connection.on('suspended', () => { + console.log('Connection suspended after extended disconnect'); + // May need manual intervention at this point }); ``` - + ## Automatic Handling -Ably SDKs automatically retry 503 errors with exponential backoff. The SDK will: -- Retry the request with increasing delays -- Maintain connection state during retries -- Resume normal operation once platform recovers -- No manual intervention needed for transient issues +Ably SDKs automatically handle 503 errors with: +- Appropriate retry strategy (not exponential backoff per editorial notes) +- Connection state preservation during retries +- Automatic reconnection when platform recovers +- Message queueing (if enabled) during temporary disconnection + +Manual retry logic is not needed and should not be implemented. ## Prevention -While 503 errors typically indicate platform-side issues beyond your control: -- Implement graceful degradation in your application -- Cache critical data locally when possible -- Monitor connection state to provide user feedback -- Consider implementing offline-first patterns for critical features +While 503 errors indicate platform-side issues, you can minimize impact: + +- **Implement gradual rollouts**: Avoid sudden traffic spikes +- **Use connection pooling**: Reduce connection overhead +- **Cache authentication tokens**: Minimize token request frequency +- **Monitor rate limits**: Stay within published limits +- **Implement circuit breakers**: Fail fast during extended outages + +## Performance Impact + +This error may affect: +- Real-time message delivery (temporary delays) +- Token authentication requests (may fail during outage) +- Push device registrations (particularly under high load) +- PubNub translator connections (if using adapter) ## Related Resources - [Ably Status Page](https://status.ably.com) -- [Connection State Management](https://ably.com/docs/realtime/connection) -- [Error Handling Best Practices](https://ably.com/docs/best-practice#error-handling) -- Related errors: [50010](./50010-edge-internal-error.md), [50210](./50210-edge-bad-gateway.md), [50410](./50410-edge-gateway-timeout.md) +- [Connection State Management](https://ably.com/docs/connect/states) +- [Connection Overview](https://ably.com/docs/connect/) +- [API Reference - Connection](https://ably.com/docs/api/realtime-sdk/connection) + +## Related Errors + +• **[50010 - Edge Internal Error](https://help.ably.io/error/50010)** + Generic edge proxy error when internal failures occur + +• **[50210 - Edge Bad Gateway](https://help.ably.io/error/50210)** + Edge proxy received invalid response from platform + +• **[50410 - Edge Gateway Timeout](https://help.ably.io/error/50410)** + Platform didn't respond within timeout period + +• **[50003 - Timeout Error](https://help.ably.io/error/50003)** + General timeout error that may occur alongside 503 errors ## Need Further Help? @@ -131,44 +165,54 @@ Our team will help you resolve this issue as quickly as possible. - + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/50400-gateway-timeout.mdx b/src/pages/docs/platform/errors/codes/50400-gateway-timeout.mdx index f295aa431d..3af051bff9 100644 --- a/src/pages/docs/platform/errors/codes/50400-gateway-timeout.mdx +++ b/src/pages/docs/platform/errors/codes/50400-gateway-timeout.mdx @@ -1,13 +1,13 @@ - + - + # Error 50400: Gateway Timeout @@ -25,8 +25,8 @@ An operation timed out while waiting for a response from Ably's infrastructure o ## Quick Fix - No immediate action required - Ably SDKs handle retry automatically -- Check [Ably status page](https://status.ably.com) if persistent -- Timeout typically resolves within seconds +- Check [Ably status page](https://status.ably.com) if persistent beyond 2 minutes +- Consider increasing timeout configuration for critical operations ## Error Messages @@ -34,45 +34,65 @@ You may see one of these messages: - "Timeout expired" - "timedEmitAsync timeout expired" - "[Operation name] timeout expired" +- "QosQueueMonitor.onQueuePollTimerExpired Failed to publish or receive message" +- "checkInherit timeout expired" +- "Unexpected error checking one of the inheritable locations" +- "BaseMonitor.init Error creating call" +- "Timeout waiting for global occupancy to become synced" ## Common Causes -1. **Temporary network delays** (60% of cases) +1. **Temporary network delays** (40% of cases) - High network latency between client and Ably - Transient connectivity issues - Regional network congestion - + -2. **Infrastructure processing delays** (30% of cases) - - Temporary high load on Ably services +2. **Infrastructure processing delays** (35% of cases) + - Redis script execution delays + - Channel coordination issues during inherit/locate operations + - Queue monitoring failures in specific regions - Database operation delays - - Channel coordination timeouts - + -3. **Long-running operations** (10% of cases) +3. **Event listener accumulation** (15% of cases) + - Excessive event listeners causing event loop delays + - Uncleaned timeout handlers building up over time + - Memory pressure from accumulated listeners + + +4. **Long-running operations** (10% of cases) - Complex channel operations - Large message processing - - Event listener accumulation - + - Global occupancy sync operations + ## Resolution Steps 1. **For transient timeouts (most cases)** - Ably SDKs automatically retry with appropriate backoff - No action required unless persistent - + - Default timeout is 5 seconds for most operations + 2. **For persistent timeouts (>2 minutes)** - Check https://status.ably.com for service incidents - Verify your network connectivity - Review recent changes to your implementation - + - Monitor specific regions if you're experiencing regional issues + + +3. **For event-related timeouts** + - Clean up event listeners after use + - Use `once` instead of `on` for single-use event handlers + - Monitor event listener count in your application + -3. **For specific operations timing out** - - Consider breaking large operations into smaller chunks - - Review timeout configuration in your implementation - - Check for event listener accumulation in your code - +4. **For specific operation timeouts** + - Consider increasing timeout configuration for critical operations + - Break large operations into smaller chunks + - Implement operation-specific retry logic if needed + ## Automatic Handling @@ -80,7 +100,8 @@ Ably SDKs automatically handle this error with: - Exponential backoff retry strategy - Connection state recovery within 2 minutes - Automatic reconnection when service recovers - +- Event cleanup for timed-out operations + The SDK will continue retrying until the operation succeeds or the connection enters a terminal state. @@ -96,12 +117,36 @@ ably.connection.on('failed', (stateChange) => { } }); -// Add timeout configuration for critical operations +// Configure timeout for critical operations const channel = ably.channels.get('critical-channel', { - params: { timeout: 10000 } // Increase timeout for critical operations + params: { timeout: 10000 } // Increase from default 5000ms }); ``` - + + +### Proper Event Listener Management +```javascript +// Use 'once' for single-use handlers to prevent accumulation +channel.once('attached', () => { + console.log('Channel attached'); +}); + +// Clean up listeners when no longer needed +const handler = (message) => { + console.log('Received:', message.data); +}; +channel.subscribe('event', handler); +// Later, when done: +channel.unsubscribe('event', handler); +``` + + +## Prevention + +- Implement proper event listener cleanup +- Use appropriate timeout values for your use case +- Monitor application memory usage and event loop health +- Consider regional distribution if experiencing location-specific timeouts ## Performance Impact @@ -109,15 +154,27 @@ This error may indicate: - Temporary service degradation in specific regions - Network path issues between client and Ably - Resource constraints during peak usage +- Event loop blocking in your application + +The error typically self-resolves within seconds to minutes. Monitor patterns to identify systemic issues. + +## Related Errors -The error typically self-resolves within seconds to minutes. +• **[50000 - Internal Server Error](https://help.ably.io/error/50000)** + General server errors that may precede or follow timeout issues + +• **[50003 - Internal Timeout](https://help.ably.io/error/50003)** + Related internal timeout scenarios within Ably services + +• **[80014 - Connection Timeout](https://help.ably.io/error/80014)** + Connection-level timeouts that differ from gateway timeouts ## Related Resources - [Connection state management](https://ably.com/docs/realtime/connection) - [Ably system status](https://status.ably.com) -- [Network requirements](https://ably.com/docs/best-practice/network-connectivity) -- Related errors: [50000](./50000-internal-server-error.md), [50003](./50003-internal-timeout.md) +- [Network and transport documentation](https://ably.com/docs/connect) +- [Event emitters in Ably SDKs](https://ably.com/docs/api/realtime-sdk) ## Need Further Help? @@ -138,40 +195,48 @@ Our team will help you resolve this issue as quickly as possible. - + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/50410-edge-proxy-gateway-timeout.mdx b/src/pages/docs/platform/errors/codes/50410-edge-proxy-gateway-timeout.mdx index f1cb5ee320..93e010b1f6 100644 --- a/src/pages/docs/platform/errors/codes/50410-edge-proxy-gateway-timeout.mdx +++ b/src/pages/docs/platform/errors/codes/50410-edge-proxy-gateway-timeout.mdx @@ -1,13 +1,13 @@ - + - + # Error 50410: Edge proxy gateway timeout @@ -32,44 +32,52 @@ Ably's edge proxy service (CloudFront) timed out waiting for a response from the You may see this message: - "Ably's edge proxy service timed out waiting for the Ably platform" +- HTTP 504 Gateway Timeout response from CloudFront ## Common Causes 1. **Temporary platform load** (60% of cases) - + - Platform service processing delays during high traffic - Temporary resource constraints in specific regions + - CI/CD pipeline stress during automated testing 2. **Network connectivity issues** (30% of cases) - + - Transient network problems between edge proxy and platform - Regional connectivity disruptions + - Edge location-specific routing issues 3. **Rare platform incidents** (10% of cases) - + - Service disruptions affecting request processing - Regional service degradation + - CloudFront configuration or routing issues ## Resolution Steps 1. **For transient errors (most cases)** - + - Ably SDKs automatically retry with exponential backoff - No manual intervention required unless persistent + - The timeout period is typically 30-60 seconds before CloudFront returns this error 2. **For persistent errors (lasting >2 minutes)** + - Check the [Ably status page](https://status.ably.com) for any ongoing incidents - Review your recent traffic patterns for unusual spikes - Note the time and region where errors occurred + - Consider whether this correlates with CI/CD pipeline runs 3. **If errors continue after status check** - Try connecting through a different network path if possible - Collect error timestamps and request IDs for support + - Note if the error occurs consistently with specific API operations ## Automatic Handling Ably SDKs automatically retry 504 gateway timeout errors with exponential backoff. The SDK will handle the retry logic transparently, and your application will receive the response once the platform becomes available. - + ## Code Examples @@ -84,10 +92,15 @@ channel.publish('update', data, (err) => { if (err) { // Only persistent failures reach here after automatic retries console.error('Failed after retries:', err); + + // Check for 50410 specifically if needed + if (err.code === 50410) { + console.log('Edge proxy timeout - check status.ably.com'); + } } }); ``` - + ## Prevention @@ -96,6 +109,7 @@ While this error is typically caused by infrastructure-level issues outside your - Implementing request batching to reduce the number of individual requests - Using Ably's regional endpoints if available for your use case - Monitoring your application's request patterns to avoid sudden traffic spikes +- Distributing load across multiple time windows for batch operations ## Performance Impact @@ -103,15 +117,29 @@ This error indicates a temporary delay but doesn't affect: - Existing WebSocket connections (they remain active) - Messages already in transit - Other channels or operations +- The CloudFront edge cache (responses are cached for 1 hour) The error only impacts the specific HTTP request that timed out. +## Related Errors + +• **[50010 - Edge Proxy Internal Error](https://help.ably.io/error/50010)** + CloudFront encountered an internal error (HTTP 500) while processing the request + +• **[50210 - Bad Gateway](https://help.ably.io/error/50210)** + CloudFront received an invalid response from the Ably platform (HTTP 502) + +• **[50310 - Service Unavailable](https://help.ably.io/error/50310)** + CloudFront received a service unavailable response from the platform (HTTP 503) + +• **[50003 - Request Timeout](https://help.ably.io/error/50003)** + Client-side timeout, different from edge proxy timeouts + ## Related Resources - [Ably Status Page](https://status.ably.com) -- [Connection State Management](https://ably.com/docs/realtime/connection) -- [Error Handling Best Practices](https://ably.com/docs/best-practice#error-handling) -- Related errors: [50003](https://help.ably.io/error/50003) (Client-side timeout), [50210](https://help.ably.io/error/50210) (Bad gateway), [50310](https://help.ably.io/error/50310) (Service unavailable) +- [Ably Documentation](https://ably.com/docs) +- [Ably Support](https://ably.com/support) ## Need Further Help? @@ -125,6 +153,8 @@ When contacting support, please provide: - Steps to reproduce the issue - Any relevant code snippets (without sensitive credentials) - The SDK and version you're using +- Whether the error occurs in specific regions or edge locations +- Any correlation with CI/CD pipeline runs or batch operations Our team will help you resolve this issue as quickly as possible. @@ -133,10 +163,10 @@ Our team will help you resolve this issue as quickly as possible. + + + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/61002-push-activation-clientid-mismatch.mdx b/src/pages/docs/platform/errors/codes/61002-push-activation-clientid-mismatch.mdx index 18c7400dbc..7eaf55c4c9 100644 --- a/src/pages/docs/platform/errors/codes/61002-push-activation-clientid-mismatch.mdx +++ b/src/pages/docs/platform/errors/codes/61002-push-activation-clientid-mismatch.mdx @@ -1,20 +1,20 @@ - + - + # Error 61002: Push activation clientId mismatch ## What Happened -Your device was previously registered for push notifications with one user identity, but you're now trying to activate it with a different user identity. +Your device was previously registered for push notifications with one user identity (clientId), but you're now trying to activate it with a different user identity. ## Quick Reference @@ -34,6 +34,7 @@ You may see one of these messages: - "Activation failed: present clientId is not compatible with existing device registration" - "clientId not compatible with local device clientId" - "Activation failed - client ID mismatch" + ## Common Causes @@ -41,19 +42,20 @@ You may see one of these messages: - Different user logged into the app - Multi-user app on same device - Logout/login with different account - + 2. **Development testing** (25% of cases) - - Switching between test accounts - - Changing authentication during development + - Switching between test accounts during development + - Changing authentication strategy mid-development - Testing multiple user scenarios - + 3. **Cached device registration** (15% of cases) - App reinstalled without proper cleanup - Device registration persisted from previous session - Migration from one authentication method to another - + - 5-second timeout during activation with existing registration + ## Resolution Steps @@ -68,7 +70,7 @@ You may see one of these messages: // Now activate with the new clientId await push.activate(); ``` - + 2. **Implement proper user switching flow** ```javascript @@ -76,21 +78,26 @@ You may see one of these messages: // When user changes, reset push notifications const push = ably.push; - // Clear existing registration - await push.deactivate(); - await push.device.reset(); - - // Re-authenticate with new clientId - const newAbly = new Ably.Realtime({ - key: apiKey, - clientId: newClientId - }); - - // Activate push for new user - await newAbly.push.activate(); + try { + // Clear existing registration + await push.deactivate(); + await push.device.reset(); + + // Re-authenticate with new clientId + const newAbly = new Ably.Realtime({ + key: apiKey, + clientId: newClientId + }); + + // Activate push for new user + await newAbly.push.activate(); + } catch (err) { + console.error('User switch failed:', err); + // Handle error appropriately + } } ``` - + 3. **Verify your current device state** ```javascript @@ -101,31 +108,79 @@ You may see one of these messages: // If they don't match, reset is required if (device.clientId && device.clientId !== ably.auth.clientId) { + console.log('ClientId mismatch detected, resetting device...'); await push.device.reset(); await push.activate(); } ``` - + + +4. **Handle the error in your activation flow** + ```javascript + try { + await push.activate(); + } catch (error) { + if (error.code === 61002) { + // ClientId mismatch - reset and retry + console.log('ClientId mismatch, resetting device registration...'); + await push.device.reset(); + await push.activate(); + } else { + // Handle other errors + throw error; + } + } + ``` + ## Automatic Handling -This error requires manual intervention - the SDK will not automatically reset device registration as this could result in lost push notifications. You must explicitly call `device.reset()` to clear the previous registration. - +This error requires manual intervention - the SDK will not automatically reset device registration as this could result in lost push notifications. When this error occurs: + +- A `SyncRegistrationFailed` event is fired in the SDK's state machine +- The device remains in its previous registration state +- You must explicitly call `device.reset()` to clear the previous registration +- This is a security feature to prevent unauthorized device takeover + + ## Prevention - **Consistent clientId**: Use the same clientId throughout the app lifecycle - **Handle user changes**: Always deactivate and reset device registration when users switch - **Clear on logout**: Reset push registration when users log out +- **Anonymous push**: Consider using anonymous push if clientId changes frequently +- **Timeout handling**: Allow sufficient time for device activation (more than 5 seconds) - **Error recovery**: Catch error 61002 and implement automatic reset flow if appropriate for your use case - + + + +## Security Context + +This error is an important security feature that: +- Prevents push notification hijacking by validating clientId consistency +- Ensures push notifications reach the intended recipient +- Maintains user identity integrity across sessions +- Implements specifications RSH3a2a1 and RSH8g for device registration security + + ## Related Resources - [Push Notifications documentation](https://ably.com/docs/push) -- [Push activation guide](https://ably.com/docs/push/activate) -- [Authentication and clientId](https://ably.com/docs/auth/identified-clients) -- Related errors: [40012](https://help.ably.io/error/40012) (Invalid client ID), [40102](https://help.ably.io/error/40102) (Incompatible credentials) +- [Identified clients and clientId](https://ably.com/docs/auth/identified-clients) +- [Push notification troubleshooting](https://faqs.ably.com/debugging-ably-push-notifications) + +## Related Errors + +• **[40012 - Invalid Client ID](https://help.ably.io/error/40012)** + General clientId validation error that can occur in various contexts + +• **[40102 - Token Expired](https://help.ably.io/error/40102)** + Authentication-level token expiration that may require re-authentication + +• **[91000 - Unable to Enter Presence](https://help.ably.io/error/91000)** + Occurs when attempting presence operations without a valid clientId ## Need Further Help? @@ -139,6 +194,8 @@ When contacting support, please provide: - Steps to reproduce the issue - Any relevant code snippets (without sensitive credentials) - The SDK and version you're using +- Whether this occurs during development or production +- Frequency of the error occurrence Our team will help you resolve this issue as quickly as possible. @@ -146,48 +203,63 @@ Our team will help you resolve this issue as quickly as possible. - + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/65536-not-an-error-code.mdx b/src/pages/docs/platform/errors/codes/65536-not-an-error-code.mdx index b1177f935b..100c8e572f 100644 --- a/src/pages/docs/platform/errors/codes/65536-not-an-error-code.mdx +++ b/src/pages/docs/platform/errors/codes/65536-not-an-error-code.mdx @@ -1,11 +1,11 @@ - + @@ -32,10 +32,25 @@ You've reached this page because you saw the number 65536 somewhere in Ably's do The number 65536 appears in several contexts within Ably: + 1. **Connection Details**: As `maxMessageSize: 65536` in connection parameters -2. **Error Messages**: When messages exceed 65536 bytes, you'll see error 40009 mentioning this limit + - Sent to clients alongside other connection settings + - Indicates the maximum allowed message size for the connection + + +2. **Error Messages**: When messages exceed 65536 bytes + - You'll see error 40009: "Maximum message length exceeded size was X bytes, limit is 65536 bytes" + - HTTP status 413 (Payload Too Large) may accompany this error + + 3. **SDK Constants**: As a configuration value in SDK source code + - Defined in transport defaults (e.g., `Defaults.maxMessageSize` in Java SDK) + - Used internally for message size validation + + 4. **Channel Flags**: As a bitwise flag value (unrelated to message size) + - `M_PRESENCE: 1 << 16` equals 65536 + - This is a different usage entirely - for channel mode flags ## Common Causes @@ -57,6 +72,7 @@ If you're experiencing issues related to the 65536 value: ### If Your Message Is Too Large + 1. **Check the actual error code** - Look for error code **40009** in your logs - The error message will state: "Maximum message length exceeded size was X bytes, limit is 65536 bytes" @@ -70,6 +86,14 @@ If you're experiencing issues related to the 65536 value: - Ensure the total size of all batched messages doesn't exceed 64KB - Split large batches into multiple publish operations + +### Environment-Specific Limits + +Be aware that message size limits may vary by environment: +- **Production accounts**: maxMessageSize = 65536 (64KB) +- **Local/sandbox accounts**: May have lower limits (e.g., 10KB) +- SDK behavior automatically adjusts based on connection details + ## The Actual Error for Size Violations When a message exceeds 65536 bytes, you'll receive: @@ -77,25 +101,29 @@ When a message exceeds 65536 bytes, you'll receive: - **HTTP Status**: 400 or 413 - **Message**: "Maximum message length exceeded" - - + + ## Technical Details + The value 65536 represents: - **Size**: 64 kilobytes (KB) - **Calculation**: 2^16 bytes - **Scope**: Maximum size for a single message's data payload - **Protocol**: Defined in Ably specification section CD2c - **Coverage**: Applied consistently across all Ably SDKs +- **Note**: Includes message data but not protocol overhead + +## Related Errors - +• **[40009 - Maximum message length exceeded](https://help.ably.io/error/40009)** + The actual error code thrown when a message exceeds the 65536 byte limit ## Related Resources - [Error 40009: Maximum message length exceeded](https://help.ably.io/error/40009) -- [Ably Limits documentation](https://ably.com/docs/general/limits) -- [Message size limits](https://faqs.ably.com/message-size-limits) +- [Message size limits FAQ](https://faqs.ably.com/message-size-limits) ## Need Further Help? @@ -116,36 +144,46 @@ Our team will help you resolve this issue as quickly as possible. - + + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/70003-integration-max-concurrency-exceeded.mdx b/src/pages/docs/platform/errors/codes/70003-integration-max-concurrency-exceeded.mdx index 0892f3c514..79bac5eb6c 100644 --- a/src/pages/docs/platform/errors/codes/70003-integration-max-concurrency-exceeded.mdx +++ b/src/pages/docs/platform/errors/codes/70003-integration-max-concurrency-exceeded.mdx @@ -1,20 +1,20 @@ - + - + # Error 70003: Integration max concurrency exceeded ## What Happened -Your Ably integration (webhooks, queues, or functions) cannot process additional messages because too many requests are already being handled concurrently. +Your Ably integration cannot process additional messages because it has reached the maximum number of concurrent requests allowed. ## Quick Reference @@ -24,16 +24,16 @@ Your Ably integration (webhooks, queues, or functions) cannot process additional ## Quick Fix -- Allow time for pending integration requests to complete before sending more messages +- Wait for current integration requests to complete before sending more messages - Review your integration rules to ensure they're not triggering unnecessarily - Consider implementing message batching to reduce integration load ## Error Messages -You may see one of these messages: +You may see this message: - "Maximum number of pending requests exceeded" - + ## Common Causes @@ -41,19 +41,19 @@ You may see one of these messages: - Sudden spikes in published messages that trigger integration rules - Multiple messages triggering the same integration simultaneously - Batch operations that generate many events at once - + 2. **Integration endpoint bottlenecks** (20% of cases) - Slow webhook response times causing requests to back up - - Downstream service unable to keep up with write volume + - Downstream service unable to keep up with write volume (e.g., BigQuery, databases) - Network latency to integration endpoints - + 3. **Overly broad integration rules** (10% of cases) - Integration rules matching more messages than intended - Multiple rules triggering for the same events - Unfiltered channel patterns causing excessive triggering - + ## Resolution Steps @@ -61,31 +61,36 @@ You may see one of these messages: - The integration system will automatically process pending requests - Messages continue to be delivered to channels normally - Integration delivery will resume once concurrency drops below the limit - + - No messages are lost - only integration delivery is delayed + 2. **Review integration volume** - Check your dashboard for message rates on channels with integration rules - Identify which rules are triggering most frequently - Look for patterns in when error 70003 occurs - + - Monitor the specific times when bursts happen + 3. **Optimize integration rules** - - Make channel filters more specific to reduce unnecessary triggering + - Make channel filters more specific using regex patterns (e.g., `^specific_channel_.*` instead of `.*`) - Review if all configured integrations are still needed - Consider combining multiple rules where appropriate - + - Remove any duplicate or overlapping rules + 4. **Improve endpoint performance** - Ensure webhook endpoints respond quickly (< 5 seconds recommended) - Implement asynchronous processing in your endpoints - Monitor your endpoint response times for bottlenecks - + - Consider using message queues for high-volume scenarios (> 25 messages/second average) + 5. **Implement traffic management** - If possible, spread message publishing over time - Consider using presence or channel state for high-frequency data - Implement client-side batching where appropriate - + - Use Ably Queues instead of webhooks for sustained high volume (> 1000 events/second) + ## Automatic Handling @@ -93,6 +98,7 @@ The Ably platform automatically manages integration concurrency: - Pending requests continue to be processed in order - New requests are queued when the limit is reached - No messages are lost - only integration delivery is delayed +- The system maintains fairness across all applications ## Prevention @@ -100,22 +106,31 @@ The Ably platform automatically manages integration concurrency: - **Monitor regularly**: Track integration performance metrics in your dashboard - **Test gradually**: Increase message volumes progressively when deploying new integrations - **Optimize endpoints**: Ensure integration endpoints can handle expected load - +- **Use appropriate integration type**: Choose webhooks for low-medium volume, queues for high volume + ## Performance Impact When this error occurs: - Channel message delivery continues normally -- Only integration delivery (webhooks, queues) is affected +- Only integration delivery (webhooks, queues, functions) is affected - Client connections and subscriptions remain unaffected - Recovery is automatic once concurrency decreases +## Related Errors + +• **[70001 - Integration Rule Failed](https://faqs.ably.com/error-code-70001)** + Occurs when an integration rule fails to execute properly due to configuration issues + +• **[70002 - Integration Operation Failed](https://faqs.ably.com/error-code-70002)** + Related error when the integration endpoint returns an unexpected response code + ## Related Resources - [Ably Integrations documentation](https://ably.com/docs/general/integrations) -- [Webhook best practices](https://ably.com/docs/general/webhooks) -- [Integration rules configuration](https://ably.com/docs/general/integrations#configure) -- Related errors: [70001](https://help.ably.io/error/70001), [70002](https://help.ably.io/error/70002) +- [Webhooks best practices](https://ably.com/docs/general/webhooks) +- [Ably Queues for high-volume scenarios](https://ably.com/docs/integrations/queues) +- [Integration rule configuration](https://ably.com/docs/general/integrations) ## Need Further Help? @@ -136,16 +151,17 @@ Our team will help you resolve this issue as quickly as possible. - @@ -156,20 +172,34 @@ Our team will help you resolve this issue as quickly as possible. - Cause 2: From DeliveryHero incident analysis in knowledge file lines 61-73 - Cause 3: From troubleshooting guidance in knowledge file lines 9-13 - Resolution Steps: - - Step 1: Technical behavior from analysis file lines 24-35 + - Step 1: Technical behavior from analysis file lines 24-35 and knowledge about automatic handling - Step 2: Troubleshooting steps from knowledge file lines 23-28 - - Step 3: Prevention strategies from knowledge file lines 39-44 - - Step 4: Best practices from knowledge file lines 39-44 - - Step 5: Rate management from knowledge file lines 30-37 -- Prevention: Based on knowledge file lines 39-44 prevention strategies + - Step 3: Prevention strategies from knowledge file lines 39-44 with specific regex example + - Step 4: Best practices from knowledge file lines 39-44 and web search on webhook rate limits + - Step 5: Rate management from knowledge file lines 30-37 and web search on queue vs webhook thresholds +- Prevention: Based on knowledge file lines 39-44 prevention strategies and web search insights +--> + + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/70004-integration-invalid-message-content.mdx b/src/pages/docs/platform/errors/codes/70004-integration-invalid-message-content.mdx index 19984de822..0da482f461 100644 --- a/src/pages/docs/platform/errors/codes/70004-integration-invalid-message-content.mdx +++ b/src/pages/docs/platform/errors/codes/70004-integration-invalid-message-content.mdx @@ -1,59 +1,61 @@ - + - + -# Error 70004: Integration Invalid Message Content +# Error 70004: Integration invalid message content -## What Happened +## What happened The Ably Integration service rejected a message because its contents don't meet the requirements of the destination service (like AWS SQS, webhooks, or functions). -## Quick Reference +## Quick reference | Error Code | HTTP Status | Category | Retryable | |------------|-------------|----------|-----------| | 70004 | 400 | Client Error (Integration) | No - requires fixing message content | -## Quick Fix +## Quick fix - Ensure message body is not empty (AWS SQS requirement) - Validate message data is properly formatted JSON - Check message size is within integration limits -## Error Messages +## Error messages You may see: - "SQS does not allow empty message body." - General integration content validation failures -## Common Causes +## Common causes 1. **Empty message body** (most common with AWS SQS) - Publishing null or undefined message data - Missing message content when SQS integration is active - + - Publishing messages without a data field + 2. **Invalid JSON in message data** - Malformed JSON that cannot be parsed - Circular references in object data - Unsupported data types for serialization - + 3. **Message content issues** - Binary data that cannot be serialized for webhook delivery - - Character encoding problems + - Character encoding problems (non-UTF-8 content) - Message size exceeding integration limits - + - Schema mismatch with integration expectations + -## Resolution Steps +## Resolution steps 1. **For AWS SQS integrations: Ensure non-empty message body** - Never publish empty or null messages to channels with SQS rules @@ -64,32 +66,51 @@ You may see: channel.publish({ name: 'event' }); // No data field channel.publish('event', null); // Null data channel.publish('event', ''); // Empty string + channel.publish('event', undefined); // Undefined data // ✅ Correct: Include message content channel.publish('event', { content: 'data' }); channel.publish('event', 'message text'); + channel.publish('event', { status: 'active' }); ``` - + 2. **Validate message format before publishing** - Ensure all data is properly serializable - Test JSON serialization before sending - Remove circular references from objects - + ```javascript + // Test serialization before publishing + try { + JSON.stringify(messageData); + channel.publish('event', messageData); + } catch (error) { + console.error('Message cannot be serialized:', error); + } + ``` + 3. **Review integration configuration** - Check the specific requirements of your integration type - Verify message format expectations for your webhook/queue - Ensure size limits are not exceeded - + - Review the integration rule settings in your Ably dashboard + 4. **Test with simple messages** - Start with basic string messages to verify integration works - Gradually add complexity to identify problematic content - Use Ably's message inspector to examine message structure - + ```javascript + // Start with simple test + channel.publish('test', 'simple string'); + + // Then try structured data + channel.publish('test', { simple: 'object' }); + ``` + -## Automatic Handling +## Automatic handling This is a validation error that will not be automatically retried. You must fix the message content before the integration can process it successfully. @@ -100,15 +121,28 @@ This is a validation error that will not be automatically retried. You must fix - **Size management**: Keep message payloads within documented limits - **Type safety**: Ensure data types match integration requirements - **Character encoding**: Use UTF-8 encoding for all text content - +- **Schema validation**: Implement client-side validation before publishing + -## Related Resources +## Related resources -- [Ably Integrations documentation](https://ably.com/docs/general/integrations) +- [Ably Integrations documentation](https://ably.com/docs/integrations) +- [AWS SQS integration guide](https://ably.com/docs/general/firehose/sqs-rule) - [Message format guidelines](https://ably.com/docs/realtime/messages) -- [AWS SQS integration guide](https://ably.com/docs/general/integrations#aws-sqs) +- [Integration limits](https://ably.com/docs/pricing/limits) -## Need Further Help? +## Related errors + +• **[70000 - Integration operation failed](https://help.ably.io/error/70000)** + General integration failure that may occur alongside content validation issues + +• **[70001 - Integration post operation failed](https://help.ably.io/error/70001)** + Occurs when the integration endpoint itself fails after content validation passes + +• **[70003 - Integration concurrent request limit](https://help.ably.io/error/70003)** + May appear if retrying invalid messages causes request queuing + +## Need further help? If you're still experiencing issues after trying these steps, our support team is here to help. @@ -127,41 +161,45 @@ Our team will help you resolve this issue as quickly as possible. - + + + + @@ -171,6 +209,6 @@ To improve this error code documentation: 1. First approach: Update editorial-notes.md in ably-os repository with specific guidance for error 70004 2. Regenerate: Run `./bin/ably-os errors document-error-codes 70004 --force` 3. For broader improvements: Review and update ably-os prompt templates -4. Context: See https://github.com/ably/ably-os/blob/main/docs/ERROR_COMMANDS_GUIDE.md +4. Context: See https://github.com/ably/ably-os/blob/5f4ba43/docs/ERROR_COMMANDS_GUIDE.md 5. Source repository: https://github.com/ably/ably-os --> \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/70005-amqp-queue-timeout.mdx b/src/pages/docs/platform/errors/codes/70005-amqp-queue-timeout.mdx index 582699e882..2d70ad20bc 100644 --- a/src/pages/docs/platform/errors/codes/70005-amqp-queue-timeout.mdx +++ b/src/pages/docs/platform/errors/codes/70005-amqp-queue-timeout.mdx @@ -1,20 +1,20 @@ - + - + # Error 70005: AMQP queue timeout ## What Happened -Ably couldn't deliver a message to your AMQP queue integration because the delivery operation timed out. +Ably couldn't deliver a message to your AMQP queue integration because the delivery operation timed out without the connection experiencing backpressure. ## Quick Reference @@ -27,94 +27,107 @@ Ably couldn't deliver a message to your AMQP queue integration because the deliv - Check your AMQP broker is responsive and not overloaded - Verify network connectivity between Ably and your queue - Monitor queue depth and consumer processing speed +- Review timeout configuration settings ## Error Messages -You may see one of these messages: +You may see this message: - "Timeout sending message to queue" ## Common Causes 1. **AMQP broker performance issues** (40% of cases) - High load on the message broker - - Slow message processing - - Resource constraints - + - Slow message processing or acceptance + - Resource constraints (CPU, memory, disk) + 2. **Network connectivity problems** (30% of cases) - High latency between Ably and your broker - Intermittent network issues - - Firewall blocking connections - + - Firewall blocking or throttling connections + 3. **Queue congestion** (20% of cases) - Target queue is full or backed up - Insufficient consumer capacity - Messages accumulating faster than processing - + 4. **Configuration issues** (10% of cases) - Incorrect integration settings - - Authentication delays - - Wrong queue names or routing keys - + - Authentication delays or handshake timeouts + - Wrong queue names, routing keys, or exchange configuration + ## Resolution Steps 1. **Check AMQP broker health** - - Access your AMQP broker management console + - Access your AMQP broker management console (RabbitMQ Management, Amazon MQ console, etc.) - Review broker performance metrics and logs - Verify CPU, memory, and disk usage are within normal ranges - Check queue depth and consumer activity - + - Look for any error messages in broker logs + 2. **Verify network connectivity** - Test connectivity from Ably's regions to your AMQP endpoint - Check network latency using monitoring tools - Review firewall rules and security groups - - Ensure Ably's IPs are whitelisted if required - + - Ensure Ably's services can reach your broker on the required ports (typically 5671 for AMQPS) + 3. **Review integration configuration** - Navigate to your Ably Dashboard → Integrations - - Verify AMQP connection settings and credentials - - Confirm queue names and routing keys are correct - - Check the configured timeout values - + - Verify AMQP connection settings and credentials are correct + - Confirm queue names and routing keys match your broker configuration + - Check the configured timeout values (if adjustable) + - Ensure the integration rule is properly configured for your channels + 4. **Optimize message flow** - Monitor message size and volume patterns - - Identify peak load times - - Scale your AMQP broker if needed + - Identify peak load times that correlate with timeouts + - Scale your AMQP broker horizontally or vertically if needed - Add more consumers to process messages faster - + - Consider implementing consumer groups for parallel processing + 5. **Implement resilience measures** - Configure dead letter queues for failed messages - - Set up appropriate retry policies + - Set up appropriate retry policies with exponential backoff - Monitor both Ably integration logs and broker metrics - - Create alerts for queue depth thresholds - + - Create alerts for queue depth thresholds and consumer lag + - Implement circuit breakers if timeout patterns persist + ## Automatic Handling -Ably's integration service will automatically retry message delivery with backoff. However, persistent timeouts may require manual intervention to resolve the underlying issue. +Ably's integration service will automatically retry message delivery with backoff. The system differentiates between timeouts with and without backpressure - this error (70005) indicates the timeout occurred without connection backpressure, suggesting the issue is likely with the destination broker or network rather than connection capacity. + ## Prevention -- **Scale appropriately**: Ensure your AMQP broker can handle peak message volumes -- **Monitor proactively**: Set up alerts for queue depth and broker performance -- **Optimize network**: Use brokers in regions close to Ably's infrastructure -- **Plan capacity**: Size your queues and consumers for expected load -- **Keep messages small**: Use compression or batching for large payloads - +- **Scale appropriately**: Ensure your AMQP broker can handle peak message volumes with headroom +- **Monitor proactively**: Set up alerts for queue depth, consumer lag, and broker performance metrics +- **Optimize network**: Use brokers in regions close to Ably's infrastructure for lower latency +- **Plan capacity**: Size your queues and consumers for expected load plus buffer +- **Keep messages small**: Use compression or batching for large payloads to reduce transmission time +- **Configure timeouts**: Work with appropriate timeout values that balance reliability and performance +- **Use persistent connections**: Implement connection pooling and keep-alive settings + ## Related Resources -- [Ably Integrations documentation](https://ably.com/docs/general/integrations) -- [AMQP queue integration guide](https://ably.com/docs/general/integrations/queues) -- [Integration rule configuration](https://ably.com/docs/general/integrations#configure) -- Related error: [70006](https://help.ably.io/error/70006) (timeout with backpressure) +- [Ably Queues documentation](https://ably.com/docs/general/queues) +- [AMQP Integration](https://ably.com/integrations/amqp) +- [Debugging Queue Rules FAQ](https://faqs.ably.com/how-can-i-debug-reactor-queues-and-queue-rules) +- [Common Queue Setup Errors](https://faqs.ably.com/common-errors-when-setting-up-queues) + +## Related Errors + +• **[70006 - AMQP timeout with backpressure](https://help.ably.io/error/70006)** + Similar timeout but with connection backpressure, indicating connection capacity issues rather than destination problems ## Need Further Help? @@ -135,19 +148,20 @@ Our team will help you resolve this issue as quickly as possible. - + + + @@ -180,6 +199,6 @@ To improve this error code documentation: 1. First approach: Update editorial-notes.md in ably-os repository with specific guidance for error 70005 2. Regenerate: Run `./bin/ably-os errors document-error-codes 70005 --force` 3. For broader improvements: Review and update ably-os prompt templates -4. Context: See https://github.com/ably/ably-os/blob/main/docs/ERROR_COMMANDS_GUIDE.md +4. Context: See https://github.com/ably/ably-os/blob/5f4ba43/docs/ERROR_COMMANDS_GUIDE.md 5. Source repository: https://github.com/ably/ably-os --> \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/70006-amqp-backpressure.mdx b/src/pages/docs/platform/errors/codes/70006-amqp-backpressure.mdx index a8ae0c53cb..aedbdd0900 100644 --- a/src/pages/docs/platform/errors/codes/70006-amqp-backpressure.mdx +++ b/src/pages/docs/platform/errors/codes/70006-amqp-backpressure.mdx @@ -1,13 +1,13 @@ - + - + # Error 70006: AMQP broker backpressure @@ -40,19 +40,19 @@ You may see one of these messages: - Broker receiving more messages than it can process - Sudden traffic spikes overwhelming the broker - Message production exceeding consumer capacity - + 2. **Resource constraints** (25% of cases) - Broker running low on memory or CPU - Disk space approaching limits - Connection pool exhaustion - + 3. **Queue backlog** (15% of cases) - Target queues full or nearing capacity - Accumulated unprocessed messages - Dead consumer connections not releasing messages - + ## Resolution Steps @@ -61,32 +61,32 @@ You may see one of these messages: - Review CPU and memory utilization metrics - Check active connection count against limits - Look for error messages in broker logs - + 2. **Verify queue status** - Check queue depths for excessive messages - Ensure consumers are connected and processing - Look for queues approaching memory or message count limits - Consider purging non-critical queues if necessary - + 3. **Scale resources if needed** - Add CPU or memory to broker nodes - Scale horizontally by adding broker cluster nodes - Increase consumer instances to process messages faster - Adjust broker configuration limits if appropriate - + 4. **Monitor and wait for recovery** - Backpressure typically resolves as broker processes queued messages - Monitor metrics to confirm improvement - Messages will be retried automatically once capacity is available - + ## Automatic Handling Ably's integration service will automatically retry message delivery when the AMQP broker recovers from backpressure. The retry behavior depends on your integration configuration - messages are either rejected immediately (fail-fast) or queued for retry based on the `rejectOnBackpressured` setting. - + ## Prevention @@ -95,14 +95,21 @@ Ably's integration service will automatically retry message delivery when the AM - **Load distribution**: Spread queues across multiple broker nodes - **Monitoring**: Set up alerts for 80% resource utilization thresholds - **Consumer scaling**: Ensure consumers can scale to match message production rate - + ## Related Resources -- [Ably Queue Integration documentation](https://ably.com/docs/general/integrations/queues) -- [Ably Integrations guide](https://ably.com/docs/general/integrations) +- [Ably Integrations documentation](https://ably.com/docs/general/integrations) - Your AMQP broker's capacity planning documentation +## Related Errors + +• **[70005 - Queue Timeout](https://help.ably.io/error/70005)** + General timeout errors when sending to AMQP queues without backpressure + +• **[50003 - Internal Timeout](https://help.ably.io/error/50003)** + Related timeout scenarios that may occur in integration processing + ## Need Further Help? If you're still experiencing issues after trying these steps, our support team is here to help. @@ -122,11 +129,11 @@ Our team will help you resolve this issue as quickly as possible. - @@ -142,23 +149,26 @@ Our team will help you resolve this issue as quickly as possible. + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/80000-connection-failed.mdx b/src/pages/docs/platform/errors/codes/80000-connection-failed.mdx index 5ac1bd93a2..82b6501a0a 100644 --- a/src/pages/docs/platform/errors/codes/80000-connection-failed.mdx +++ b/src/pages/docs/platform/errors/codes/80000-connection-failed.mdx @@ -1,11 +1,11 @@ - + @@ -25,7 +25,7 @@ Your application cannot establish a connection to Ably's servers, preventing all ## Quick Fix - Check your internet connection is working -- Verify your API key is correct and not expired +- Verify your API key is correct and not expired - Ensure ports 80 and 443 are not blocked by firewalls ## Error Messages @@ -44,25 +44,25 @@ You may see one of these messages: - No internet connection - Corporate firewall blocking WebSocket connections - Proxy server configuration problems - + 2. **Invalid credentials** (25% of cases) - Incorrect API key - Expired authentication token - Wrong environment (sandbox vs production) - + 3. **SSL/TLS certificate issues** (10% of cases) - Certificate chain validation failures (especially on Android) - SSL handshake failures - Outdated TLS version - + 4. **Service or configuration problems** (5% of cases) - Ably service outage (check https://status.ably.com) - Incorrect endpoint URLs - All transport methods exhausted - + ## Resolution Steps @@ -70,20 +70,20 @@ You may see one of these messages: - Test your internet connection by accessing other websites - Try connecting from a different network to rule out local network issues - Check if WebSocket connections are allowed (test at https://www.websocket.org/echo.html) - + 2. **Check your API credentials** - Log into your [Ably dashboard](https://ably.com/dashboard) - Navigate to your app → "API Keys" tab - Verify you're using the complete API key (including app ID prefix) - Ensure the key has appropriate capabilities for your operations - + 3. **Test network access to Ably** - Verify ports 80 (HTTP) and 443 (HTTPS) are open - If behind a corporate firewall, check WebSocket connections are allowed - For proxy environments, ensure proper proxy configuration - + 4. **Review your client configuration** ```javascript @@ -114,7 +114,7 @@ Ably SDKs automatically handle this error with the following behavior: - **Subsequent retries**: Exponential backoff with jitter - **State progression**: `disconnected` → `connecting` → `connected` (on success) or `suspended` (after multiple failures) - **No manual retry needed**: The SDK manages all reconnection attempts - + ## Prevention @@ -122,7 +122,7 @@ Ably SDKs automatically handle this error with the following behavior: - **Handle offline scenarios**: Design your application to gracefully handle periods without connectivity - **Use environment variables**: Store API keys securely and avoid hardcoding credentials - **Test across networks**: Verify your application works in various network environments during development - + ## Platform-Specific Considerations @@ -130,18 +130,29 @@ Ably SDKs automatically handle this error with the following behavior: - Higher incidence of SSL chain validation failures - May require specific SSL/TLS configuration for older Android versions - Consider implementing certificate pinning for enhanced security - + ### Java SDK - Known issue: WebSocket thread leak on repeated connection failures ([Issue #1144](https://github.com/ably/ably-java/issues/1144)) - Workaround: Monitor thread count and restart if necessary for long-running applications - + ### Corporate Networks - WebSocket connections frequently blocked - May require fallback to HTTP transport - Consider configuring transport options explicitly - + + +## Related Errors + +• **[80002 - Connection Suspended](https://help.ably.io/error/80002)** + Occurs after 2+ minutes of disconnection when recovery attempts have failed + +• **[80003 - Connection Disconnected](https://help.ably.io/error/80003)** + Temporary disconnection with quick automatic retry + +• **[80017 - Connection Closing](https://help.ably.io/error/80017)** + Connection is being intentionally closed by the client ## Related Resources @@ -149,7 +160,6 @@ Ably SDKs automatically handle this error with the following behavior: - [Authentication guide](https://ably.com/docs/auth) - [Transport configuration](https://ably.com/docs/realtime/connection#transport-params) - [Network requirements](https://ably.com/docs/best-practice-guide#connectivity) -- Related errors: [80002 (Suspended)](./80002-connection-suspended.md), [80003 (Disconnected)](./80003-connection-disconnected.md) ## Need Further Help? @@ -170,19 +180,19 @@ Our team will help you resolve this issue as quickly as possible. - - + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/80002-connection-suspended.mdx b/src/pages/docs/platform/errors/codes/80002-connection-suspended.mdx index 3b79ecc3c9..ea3b8196be 100644 --- a/src/pages/docs/platform/errors/codes/80002-connection-suspended.mdx +++ b/src/pages/docs/platform/errors/codes/80002-connection-suspended.mdx @@ -1,20 +1,20 @@ - + - + # Error 80002: Connection suspended ## What Happened -Your connection to Ably has been suspended after network connectivity issues prevented a stable connection for more than 2 minutes. +Your connection to Ably has been suspended after being unable to establish or maintain a stable connection for more than 2 minutes, indicating persistent network connectivity issues. ## Quick Reference @@ -26,7 +26,8 @@ Your connection to Ably has been suspended after network connectivity issues pre - Check your internet connection stability - Verify WebSocket connections aren't blocked by firewall or proxy -- Connection will automatically retry every 15-30 seconds +- SDK automatically retries every 30 seconds while suspended +- Consider manually triggering reconnection if needed ## Error Messages @@ -36,84 +37,120 @@ You may see one of these messages: - "Unable to establish connection" (when no connection was ever established) - "Unable to publish in Suspended state" - "Connection suspended due to server unavailability code=80002" +- "Message cannot be published. Client is not allowed to queue messages when connection is in Suspended state" ## Common Causes -1. **Network connectivity issues** (70% of cases) - - - Intermittent WiFi or cellular connectivity - - Moving between cell towers or poor signal areas - - Network interruptions lasting more than 2 minutes +1. **Extended network connectivity issues** (70% of cases) + + - Intermittent WiFi or cellular connectivity lasting over 2 minutes + - Moving between cell towers or extended poor signal areas + - Network interruptions preventing connection for extended periods 2. **Network configuration problems** (20% of cases) - + - Corporate firewalls blocking WebSocket connections - Proxy servers interfering with persistent connections - - Restrictive network policies + - Restrictive network policies preventing long-lived connections -3. **Extended authentication issues** (10% of cases) - +3. **Authentication or initialization issues** (10% of cases) + - Token refresh failures during connection attempts - Credential validation taking too long + - Initial connection never established due to configuration issues ## Resolution Steps 1. **Verify network connectivity** - + - Test your internet connection stability - Try switching between WiFi and cellular data - Move to a location with better signal strength + - Check if the issue persists across different devices 2. **Check network environment** - + - Test from a different network (home, office, mobile hotspot) - Verify WebSocket connections are allowed on port 443 - Check if corporate firewall or proxy is interfering - -3. **Monitor connection state** - - - The SDK will automatically retry connection every 15-30 seconds - - No manual intervention required - automatic recovery is built-in - - Connection will transition back to `connected` state when network improves - -4. **Handle suspended state in your application** - - - Show appropriate UI feedback to users about connection status - - Queue critical operations locally if needed - - Wait for connection state to become `connected` before resuming operations + - Ensure your network allows long-lived connections + +3. **Understand the suspended state behavior** + + - Connection enters suspended after 2 minutes of failed attempts + - SDK automatically retries every 30 seconds (not 15 seconds like disconnected state) + - Messages cannot be published or queued while suspended + - All channels are automatically suspended + +4. **Handle recovery in your application** + + - Monitor connection state changes in your app + - When connection recovers, channels will automatically reattach + - Use the history API to retrieve messages missed during suspension + - Implement appropriate UI feedback for users during suspension + +5. **Manual recovery options** + + - Explicitly call `connection.connect()` to trigger immediate retry + - Restart your application to clear any resource issues + - Update to the latest SDK version if issues persist ## Automatic Handling Ably SDKs automatically handle connection suspension with these behaviors: - -- Retry connection attempts every 15-30 seconds while suspended + +- Retry connection attempts every 30 seconds while suspended - Automatically transition back to `connected` when network recovers -- No exponential backoff needed - SDK manages retry timing -- Messages cannot be published while in suspended state +- Channels automatically reattach after connection is restored +- No message queueing during suspended state - publishing will fail immediately +- Connection state recovery is not possible after suspension ## Prevention - + - Design your app to gracefully handle extended offline periods - Implement proper connection state monitoring +- Show appropriate UI feedback when connection is suspended - Test your app under poor network conditions - Consider offline functionality for core features +- Use connection state listeners to detect suspension early ## Performance Impact While connection is suspended: - + - All realtime features (channels, presence, messaging) are unavailable -- Publishing operations will fail with error 80002 +- Publishing operations will fail immediately with error 80002 - Presence members are removed from channels - Recovery may take several minutes depending on network conditions +- Message continuity is lost - use history API to catch up after recovery + +## Understanding Connection States + + +The suspended state differs from other connection states: + +- **Disconnected**: Temporary issue, retries every 15 seconds, messages queue +- **Suspended**: Extended issue (2+ minutes), retries every 30 seconds, no queueing +- **Failed**: Terminal state requiring manual intervention +- **Closed**: Connection intentionally closed ## Related Resources -- [Connection State Management](https://ably.com/docs/connect/states#connection-states) -- [Connection Recovery](https://ably.com/docs/connect/recovery) -- [Network Requirements](https://ably.com/docs/connect#network-requirements) -- Related errors: [80000](./80000-connection-failed.md) (connection failed), [80003](./80003-disconnected.md) (disconnected) +- [Connection State Management](https://ably.com/docs/connect/states) +- [Connection Recovery](https://faqs.ably.com/connection-state-recovery) +- [Publishing Messages FAQ](https://faqs.ably.com/will-i-receive-an-error-if-a-client-publishes-with-the-connection-in-the-failed-disconnected-or-suspended-states) + +## Related Errors + +• **[80000 - Connection Failed](https://help.ably.io/error/80000)** + Terminal connection failure requiring manual intervention, unlike suspended which auto-retries + +• **[80003 - Disconnected](https://help.ably.io/error/80003)** + Temporary disconnection with message queueing, unlike suspended state + +• **[80008 - Unable to Recover Connection](https://help.ably.io/error/80008)** + May occur after suspension when connection state cannot be recovered ## Need Further Help? @@ -134,22 +171,25 @@ Our team will help you resolve this issue as quickly as possible. - @@ -157,22 +197,27 @@ Our team will help you resolve this issue as quickly as possible. - Common Causes: - Cause 1: Based on knowledge file lines 11-17 describing network connectivity scenarios - Cause 2: Based on knowledge file lines 11-17 describing configuration problems - - Cause 3: Based on knowledge file lines 11-17 describing authentication issues + - Cause 3: Based on knowledge file lines 14-15 describing authentication issues - Resolution Steps: - Step 1: FAQ advice from knowledge file lines 35-43 - preserved for customer experience - Step 2: FAQ advice from knowledge file lines 44-47 - network environment checks - - Step 3: Analysis file lines 87-88 and knowledge file lines 113-114 - automatic recovery behavior - - Step 4: Ably documentation and editorial notes guidance on state handling + - Step 3: Editorial notes lines 164-167 and analysis file lines 87-88 - suspended state behavior + - Step 4: Knowledge file lines 77-84 and web search results - recovery handling + - Step 5: Web search results - manual recovery options - Prevention: Based on knowledge file lines 55-75 best practices section - Performance Impact: Based on knowledge file lines 19-24 describing service impact +- Understanding Connection States: Based on editorial notes lines 157-167 critical connection state information --> + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/80003-connection-temporarily-unavailable.mdx b/src/pages/docs/platform/errors/codes/80003-connection-temporarily-unavailable.mdx index c99581748f..bf9d8fbc53 100644 --- a/src/pages/docs/platform/errors/codes/80003-connection-temporarily-unavailable.mdx +++ b/src/pages/docs/platform/errors/codes/80003-connection-temporarily-unavailable.mdx @@ -1,13 +1,13 @@ - + - + # Error 80003: Connection temporarily unavailable @@ -25,6 +25,7 @@ Your app temporarily lost its connection to Ably, which is completely normal and ## Quick Fix - No action required - the SDK automatically reconnects within 15 seconds +- With default settings, messages are queued during disconnection - Monitor if disconnections are excessive (multiple times per minute) - Ensure your app handles brief disconnections gracefully @@ -37,98 +38,162 @@ You may see one of these messages: - "Transport operation timed out" - "Unable to connect (network unreachable)" - "Unable to connect (no available host)" +- "Unable to connect (and no more fallback hosts to try)" - "No activity seen from realtime in {interval}; assuming connection has dropped" - "Transport disconnected unexpectedly" +- "Request cancelled" +- "Connection closed" +- "Idle timer expired" - "Connection timeout after 3 seconds" (CLI only) - "No network connection available" (Android) -- "Idle timer expired" +- "Cannot send a ping when the connection is {state}" (Ruby) +- "Ping failed as connection has changed state to {state}" (Ruby) ## Common Causes 1. **Normal network interruptions** (80% of cases) - + - Brief WiFi hiccups or network maintenance - Cell tower handoffs on mobile devices - Network equipment resets or updates + - WebSocket connections interrupted by proxies or firewalls 2. **Mobile device behavior** (15% of cases) - + - Switching between WiFi and cellular data - Device sleep/wake cycles - Background app transitions - Battery optimization pausing network activity + - Operating system network management 3. **Authentication updates** (5% of cases) - + - Token renewal causing momentary disconnection - Credential updates requiring reconnection + - Authentication refresh cycles ## Resolution Steps 1. **Let the SDK handle it automatically** - + - Ably SDKs automatically reconnect after detecting a disconnection - Reconnection typically happens within 15 seconds - No manual intervention required for normal disconnections + - Messages are automatically queued with default settings (`queueMessages: true`) -2. **Design your app for resilience** - +2. **Understand connection states** + + - With default settings, you can publish immediately after SDK initialization + - Messages are automatically queued in `initialized`, `connecting`, and `disconnected` states + - Only in `suspended` (after 2+ minutes) or `failed` states will publishing fail + - No need to wait for connection unless you've explicitly set `queueMessages: false` + +3. **Design your app for resilience** + - Queue user actions during brief disconnections - Implement optimistic UI updates - Cache important data locally - Show subtle connection indicators only after a few seconds + - Don't block user interactions during disconnections -3. **Monitor for excessive disconnections** - +4. **Monitor for excessive disconnections** + - Check network stability if disconnections happen multiple times per minute - Test on different networks (WiFi vs cellular) - Monitor patterns - specific times, locations, or activities + - Review app behavior during state transitions -4. **For persistent issues** - +5. **For persistent issues** + - If disconnections never resolve automatically - If all users in a region experience frequent disconnections + - If the SDK gets stuck in disconnected state (rare) - Contact support with connection logs and patterns ## Automatic Handling Ably SDKs handle 80003 errors automatically: - + - Immediate detection of connection loss - Exponential backoff retry strategy - Automatic reconnection within 15 seconds - Message queueing during disconnection (with default settings) - State recovery after reconnection +- Transport fallback (WebSocket → HTTP streaming → HTTP polling) + +## Connection State Behavior + + +| State | Can Publish? | Behavior | +|-------|-------------|----------| +| `initialized` | ✅ Yes (queued) | Messages queued until connected | +| `connecting` | ✅ Yes (queued) | Messages queued until connected | +| `connected` | ✅ Yes | Messages sent immediately | +| `disconnected` | ✅ Yes with default settings | Messages queued by default | +| `suspended` | ❌ No | Entered after 2+ min disconnected | +| `closed` | ❌ No | No connection exists | +| `failed` | ❌ No | Terminal error state | ## Prevention While disconnections are normal and can't be eliminated entirely, you can minimize their impact: - + - **Connection Monitoring**: Track patterns to identify unusual behavior - **Network Optimization**: Use stable connections where possible - **Graceful Degradation**: Design features to work during brief offline periods - **User Experience**: Don't alarm users with error messages for brief disconnections +- **Battery Settings**: Be aware of battery optimization effects on network activity ## Platform-Specific Considerations ### Android - + - Android 14+ may experience connection instability in background +- SDK may cycle between connected-disconnected states repeatedly when backgrounded - Consider closing connection when backgrounded with a delay - Reconnect when returning to foreground +- In rare cases, SDK can get stuck in disconnected state (requires app restart) ### Browser - + - Browser performs connectivity check to `internet-up.ably-realtime.com` - Shows "Unable to connect (network unreachable)" when offline +- WebSocket errors with code 1006 may indicate server or client-side disconnection + +### iOS/macOS + +- May show "Idle timer expired" for long-inactive connections +- Connection closed messages differentiate between disconnected and closed states + +### CLI + +- Uses shorter 3-second timeout for connection establishment +- Designed for quick command execution rather than long-lived connections + +## Related Errors + +• **[80000 - Connection Failed](https://help.ably.io/error/80000)** + More severe connection failure that may require manual intervention + +• **[80002 - Connection Suspended](https://help.ably.io/error/80002)** + Connection suspended after prolonged disconnection (2+ minutes) + +• **[80013 - Protocol Error](https://help.ably.io/error/80013)** + Protocol version mismatch or violation requiring SDK update + +• **[80014 - Connection Timeout](https://help.ably.io/error/80014)** + Initial connection establishment timeout, different from temporary disconnection + +• **[40140-40149 - Token Expiration](https://help.ably.io/error/40140)** + Token-related disconnections that trigger automatic renewal ## Related Resources -- [Connection States Documentation](https://ably.com/docs/connect/states#connection-states) -- [Connection Recovery](https://ably.com/docs/connect/states#connection-recovery) -- [Connection State Events](https://ably.com/docs/connect/states#connection-state-events) -- [Network Connectivity Best Practices](https://ably.com/docs/best-practice#connectivity) +- [Connection States Documentation](https://ably.com/docs/realtime/connection) +- [Connection Recovery](https://ably.com/docs/connect) +- [Network Connectivity Best Practices](https://ably.com/docs/best-practice) +- [Status Page](https://status.ably.com) ## Need Further Help? @@ -142,6 +207,8 @@ When contacting support, please provide: - Steps to reproduce the issue - Any relevant code snippets (without sensitive credentials) - The SDK and version you're using +- Frequency and patterns of disconnections +- Network environment details Our team will help you resolve this issue as quickly as possible. @@ -149,36 +216,51 @@ Our team will help you resolve this issue as quickly as possible. - + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/80008-connection-recovery-expired.mdx b/src/pages/docs/platform/errors/codes/80008-connection-recovery-expired.mdx index a97d4879b9..dd64fd8f99 100644 --- a/src/pages/docs/platform/errors/codes/80008-connection-recovery-expired.mdx +++ b/src/pages/docs/platform/errors/codes/80008-connection-recovery-expired.mdx @@ -1,20 +1,20 @@ - + - + # Error 80008: Connection recovery expired ## What happened -Your app attempted to resume a previous connection to Ably, but the connection had already expired (typically after 2 minutes of disconnection). +Your app attempted to resume a previous connection to Ably, but the connection had already expired (typically after 2 minutes of disconnection). This is normal behavior after extended disconnections. ## Quick reference @@ -27,108 +27,167 @@ Your app attempted to resume a previous connection to Ably, but the connection h - Let the SDK establish a fresh connection automatically - All channels will reattach with `resumed=false` - Use the history API to retrieve any messages sent during disconnection +- Re-enter presence if your app uses presence features ## Error messages You may see one of these messages: - "Unable to recover connection (connection expired)" - Connection state has been cleaned up after 2 minutes -- "Unable to recover connection (unretrievable)" - Recovery data could not be accessed +- "Unable to recover connection (unretrievable)" - Recovery data could not be accessed from server storage + + ## Common causes - -1. **Extended disconnection** (90% of cases) + +1. **Extended disconnection** (85% of cases) - App disconnected for more than 2 minutes - Mobile app backgrounded for extended period - Device in sleep mode or airplane mode - Network outage lasting over 2 minutes - -2. **Network instability** (8% of cases) +2. **Network instability** (10% of cases) - Prolonged poor network conditions preventing timely reconnection - Connection attempts failing repeatedly during the 2-minute window + - Network switching (WiFi to mobile data) taking too long -3. **App lifecycle events** (2% of cases) +3. **App lifecycle events** (5% of cases) - User switching between apps for extended periods - Browser tab suspended or inactive + - Server processes idle for extended periods (publish-only servers) + - Page refresh attempting to recover previous connection ## Resolution steps - + 1. **Accept the fresh connection** - - The SDK automatically establishes a new connection + - The SDK automatically establishes a new connection with a new connection ID - No manual intervention required for the connection itself - All channels automatically reattach without the resume flag + - Monitor connection state changes to confirm new connection: + ```javascript + ably.connection.on('connected', (stateChange) => { + if (stateChange.reason?.code === 80008) { + console.log('Fresh connection established after recovery failure'); + // Your app-specific recovery logic here + } + }); + ``` + - + 2. **Handle potential message gaps** - If message continuity is critical, use the history API: ```javascript // Retrieve messages from the last known point const history = await channel.history({ - start: lastKnownMessageTimestamp + start: lastKnownMessageTimestamp, + limit: 100 }); - // Process missed messages - history.items.forEach(message => { + // Process missed messages in reverse chronological order + for (const message of history.items) { if (message.timestamp > lastKnownMessageTimestamp) { processMessage(message); } - }); + } ``` - + - -3. **Restore application state** - - Re-enter presence if your app uses presence features - - Rebuild any connection-dependent state - - Update UI to reflect fresh connection status - - -4. **Monitor connection state for debugging** + +3. **Restore presence state** + - Presence members are automatically re-entered in most cases + - Exception: When using page refresh recovery, you must explicitly re-enter: ```javascript - ably.connection.on('connected', (stateChange) => { - if (stateChange.reason?.code === 80008) { - console.log('Fresh connection established after recovery failure'); - // Handle recovery failure if needed - } - }); + // Re-enter presence after fresh connection + if (stateChange.reason?.code === 80008) { + await channel.presence.enter({ + name: userName, + status: 'online' + }); + } ``` - + + + +4. **Implement robust state management** + - Store critical application state locally + - Track the last processed message ID or timestamp + - Design your app to handle fresh connections gracefully + - Consider implementing a reconnection strategy for critical applications ## Automatic handling - + Ably SDKs automatically handle this error by: - Establishing a fresh connection with a new connection ID - Reattaching all channels (with `resumed=false`) - Re-entering presence members (except when using page refresh recovery) -- No manual reconnection logic needed +- No manual reconnection logic needed - the SDK manages this transparently + +## SDK-specific behaviors + + +### Java SDK +- Connection ID changes are logged with both old and new IDs +- Example log: `Connection aZrEvfc5AM couldn't recover aZrEvfc5AMoTnBl-, new connection McyZbFD8k9 established` +- State transition: connected → connecting → connected (with new ID) + +### Go SDK +- Versions prior to 1.2.15 had issues with channel reattachment after recovery failure +- Ensure you're using version 1.2.15 or later for proper handling + +### JavaScript SDK +- Transport idle timer expires after 10100ms of inactivity +- Browser page refresh requires explicit presence re-entry +- Supports connection recovery via URL parameter ## Prevention - + - **Mobile apps**: Handle foreground/background transitions properly - **Connection monitoring**: Implement connection state monitoring for critical applications - **State management**: Design your app to handle fresh connections gracefully - **History persistence**: Enable channel persistence if message continuity is critical +- **Idle servers**: For publish-only servers, consider periodic heartbeat messages to maintain connection ## Understanding connection recovery - + Ably maintains connection state for 2 minutes after disconnection: -- **Within 2 minutes**: Connections can resume with full state recovery -- **After 2 minutes**: Connection state is cleaned up to conserve resources +- **Within 2 minutes**: Connections can resume with full state recovery, maintaining message continuity +- **After 2 minutes**: Connection state is cleaned up from server storage to conserve resources - **Fresh connection**: A new connection is established with new connection ID +- **Non-fatal error**: This is normal behavior, not a failure - it ensures efficient resource management + +The 2-minute window balances quick recovery capabilities with server resource efficiency. -This is normal behavior and not a failure - it ensures efficient resource management while providing a reasonable recovery window. +## Performance impact + + +This error has minimal performance impact: +- Fresh connection establishment is fast (typically < 1 second) +- Channels reattach automatically in parallel +- No impact on other connections or channels +- Message publishing can resume immediately after connection ## Related resources -- [Connection state recovery documentation](https://ably.com/docs/connect/states#connection-state-recovery) +- [Connection state recovery documentation](https://ably.com/docs/connect/states) - [History API for message retrieval](https://ably.com/docs/storage-history/history) -- [Presence recovery patterns](https://ably.com/docs/presence/presence#connection-recovery) -- Related errors: [80002](https://help.ably.io/error/80002) (suspended state), [80003](https://help.ably.io/error/80003) (disconnected state) +- [Presence recovery patterns](https://ably.com/docs/presence-occupancy/presence) +- [Connection states explained](https://ably.com/docs/connect/) + +## Related errors + +• **[80002 - Connection suspended](https://help.ably.io/error/80002)** + Occurs when disconnection exceeds 2 minutes and connection enters suspended state + +• **[80003 - Connection disconnected](https://help.ably.io/error/80003)** + Temporary disconnection state before attempting recovery + +• **[80000 - Connection failed](https://help.ably.io/error/80000)** + Terminal connection failure requiring manual intervention ## Need further help? @@ -149,45 +208,74 @@ Our team will help you resolve this issue as quickly as possible. - + + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/80009-connection-transport-unavailable.mdx b/src/pages/docs/platform/errors/codes/80009-connection-transport-unavailable.mdx index b204e558d6..ac6d360243 100644 --- a/src/pages/docs/platform/errors/codes/80009-connection-transport-unavailable.mdx +++ b/src/pages/docs/platform/errors/codes/80009-connection-transport-unavailable.mdx @@ -1,20 +1,20 @@ - + - + # Error 80009: Connection transport unavailable ## What Happened -The connection to Ably exists but the underlying network transport that carries data is missing or unavailable. +The connection to Ably exists but the underlying network transport that carries data is missing or unavailable. The connection details exist but there's no way to actually communicate. ## Quick Reference @@ -41,19 +41,22 @@ You may see one of these messages: - Network transport never properly initialized - Transport cleaned up while still needed - Platform-specific network restrictions - + - Operating system network layer issues + 2. **Authentication operation failures** (30% of cases) - Auth callback throwing exceptions - Auth URL request failing or timing out - Token request operations interrupted - + - Timeout during auth operations + 3. **Comet transport issues** (10% of cases - historical) - Comet fallback transport failing on certain browsers - Transport POST requests returning 404 - Windows Chrome environments affected - + - Angular applications experiencing transport errors + ## Resolution Steps @@ -75,13 +78,14 @@ You may see one of these messages: }); }, 1000); ``` - + 2. **For authentication-related failures (Ruby SDK)** - Verify auth callback completes within timeout period - Check auth URL endpoint is responsive - Ensure network connectivity during token requests - + - Increase auth_request_timeout if needed + 3. **For legacy Comet transport issues** ```javascript @@ -91,18 +95,26 @@ You may see one of these messages: transports: ['web_socket'] }); ``` - + 4. **Monitor system resources** - Check device memory usage - Restart app if memory usage is high - Close other network-intensive applications - + - Monitor for resource exhaustion patterns + + +5. **Network environment checks** + - Test on different networks (WiFi vs cellular) + - Check if network proxy or firewall is interfering + - Verify WebSocket connectivity is not blocked + - Try connecting from a different location + ## Automatic Handling -Ably SDKs do not automatically recover from this error. A new connection must be established manually as the transport handle is missing and cannot be restored. - +Ably SDKs do not automatically recover from this error. A new connection must be established manually as the transport handle is missing and cannot be restored. The connection appears active but cannot actually send or receive data. + ## Prevention @@ -110,14 +122,26 @@ Ably SDKs do not automatically recover from this error. A new connection must be - Don't attempt to reuse connection objects that have failed - Implement proper connection lifecycle management - For web applications, consider forcing WebSocket transport if Comet issues occur - +- Monitor app memory usage and release unused resources promptly +- Implement robust error detection for connection issues + ## Related Resources -- [Connection state management](https://ably.com/docs/realtime/connection) +- [Connection state and recovery](https://ably.com/docs/connect/states) - [Authentication documentation](https://ably.com/docs/auth) -- [Transport selection](https://ably.com/docs/realtime/connection#transport) -- Related errors: [80000](https://help.ably.io/error/80000), [80002](https://help.ably.io/error/80002), [80003](https://help.ably.io/error/80003) +- [WebSocket transport guide](https://ably.com/docs/client-lib-development-guide/websocket) + +## Related Errors + +• **[80000 - Connection Failed](https://help.ably.io/error/80000)** + General connection failure requiring SDK update or configuration fix + +• **[80002 - Connection Suspended](https://help.ably.io/error/80002)** + Connection suspended after extended disconnection period + +• **[80003 - Connection Disconnected](https://help.ably.io/error/80003)** + Temporary disconnection with automatic reconnection attempts ## Need Further Help? @@ -138,37 +162,42 @@ Our team will help you resolve this issue as quickly as possible. - + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/80010-invalid-transport-handle.mdx b/src/pages/docs/platform/errors/codes/80010-invalid-transport-handle.mdx index b610f277a0..dd6bb00414 100644 --- a/src/pages/docs/platform/errors/codes/80010-invalid-transport-handle.mdx +++ b/src/pages/docs/platform/errors/codes/80010-invalid-transport-handle.mdx @@ -1,13 +1,13 @@ - + - + # Error 80010: Invalid transport handle @@ -40,17 +40,17 @@ The message includes the actual connection state for debugging purposes. 1. **Attempting operations during state transitions** (most common) - Trying to publish or subscribe while connection is changing states - Race conditions between multiple connection operations - + 2. **Invalid connection state** - Connection is in an unexpected or undefined state - Transport handle has been superseded or invalidated - + 3. **SDK lifecycle issues** - Improper connection initialization sequence - Missing state validation before operations - + ## Resolution Steps @@ -88,19 +88,19 @@ The message includes the actual connection state for debugging purposes. } } ``` - + 3. **Handle timing and race conditions** - Avoid rapid successive connection operations - Use connection promises or callbacks instead of assuming immediate state - Implement proper error handling for state conflicts - + 4. **Review your connection management** - Ensure proper SDK initialization - Verify connection lifecycle handling - Check for concurrent operations that might conflict - + ## Automatic Handling @@ -112,19 +112,29 @@ The Ably SDK does not automatically retry this error as it indicates a client-si - **Use event-driven patterns** - listen for connection state changes rather than assuming state - **Implement proper error handling** for all connection operations - **Design for connection lifecycle** - structure your app flow around connection states - + ## Platform Information This error code is specific to the **iOS/macOS (Cocoa) SDK**. Other SDKs may handle similar scenarios with different error codes or mechanisms. - + ## Related Resources -- [Connection State Management](https://ably.com/docs/realtime/connection#connection-state-explained) -- [iOS SDK Documentation](https://ably.com/docs/realtime/usage#connection) -- [Connection State Recovery](https://ably.com/docs/realtime/connection#connection-state-recovery) -- Related errors: [80000](https://help.ably.io/error/80000) (connection failed), [80003](https://help.ably.io/error/80003) (disconnected), [80009](https://help.ably.io/error/80009) (connection not established) +- [Connection State Management](https://ably.com/docs/connect/states) +- [iOS SDK Documentation](https://ably.com/docs/api/realtime-sdk/connection) +- [Connection State Recovery](https://ably.com/docs/connect/states#connection-state-recovery) + +## Related Errors + +• **[80000 - Connection Failed](https://help.ably.io/error/80000)** + Connection could not be established, terminal failure state + +• **[80003 - Disconnected](https://help.ably.io/error/80003)** + Connection dropped but will automatically retry + +• **[80009 - Connection Not Established](https://help.ably.io/error/80009)** + No transport handle exists for the connection yet ## Need Further Help? @@ -145,15 +155,18 @@ Our team will help you resolve this issue as quickly as possible. - + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/80013-protocol-error.mdx b/src/pages/docs/platform/errors/codes/80013-protocol-error.mdx index 5b10abd29e..10a673c972 100644 --- a/src/pages/docs/platform/errors/codes/80013-protocol-error.mdx +++ b/src/pages/docs/platform/errors/codes/80013-protocol-error.mdx @@ -1,13 +1,13 @@ - + - + # Error 80013: Protocol Error @@ -26,86 +26,154 @@ The communication between your application and Ably's servers encountered a prot - Update to the latest version of your Ably SDK - Verify your message formats match Ably's protocol specification -- Check that all required fields are present in your messages +- For Go SDK with MessagePack: Convert structs to strings or use JSON encoding +- For delta encoding errors: The SDK will automatically trigger recovery ## Error Messages -You may see one of these messages: +You may see one of these error messages: + +### Protocol Action Errors - "Protocol Message Action {action} is unsupported by this MessageDispatcher" - "Protocol error, unknown presence action {action}" + +### Missing Field Errors - "Protocol error, presence message is missing connectionId" + +### Validation Errors - "Invalid Protocol Message received: {event_data}" +- "Connection moving to the failed state as the protocol is invalid and unsupported" + +### Encoding Errors +- "msgpack encode error: unsupported payload type status=0, internal=80013" (Go SDK) - "protocol error" (with encoding details) -- "msgpack encode error: unsupported payload type status=0, internal=80013" + +### Delta Encoding Errors +- "Failed to decode data: Decoder was not initialized with a valid base" +- Recovery warning: "starting delta decode failure recovery process" ## Common Causes 1. **SDK version incompatibility** (40% of cases) - Using outdated SDK that doesn't support current protocol features - SDK version mismatch with server protocol version - + - Missing support for newer protocol actions + -2. **Missing required fields** (30% of cases) +2. **Missing required fields** (25% of cases) - Presence messages lacking connectionId - Protocol messages missing mandatory fields - + - Incomplete message structure + 3. **Invalid message actions** (20% of cases) - Unknown protocol message action types - Unsupported presence actions - + - Actions not implemented in current SDK version + 4. **Encoding failures** (10% of cases) - - MessagePack encoding errors with struct/object data + - MessagePack encoding errors with struct/object data in Go SDK - Delta decode failures with VCDiff encoding - + - JSON/MessagePack serialization issues + + +5. **Network interference** (5% of cases) + - Proxy servers modifying WebSocket traffic + - Firewalls corrupting protocol messages + - Network packet loss causing message corruption + ## Resolution Steps -1. **Update your SDK to the latest version** - - Check your current SDK version against the [latest releases](https://ably.com/download) - - Review the [changelog](https://github.com/ably/ably-js/releases) for protocol updates - - Update your dependencies and test in a staging environment - - -2. **Verify message format compliance** - - Ensure all required fields are present (especially connectionId for presence messages) - - Follow the [protocol documentation](https://ably.com/docs/realtime/protocol) strictly - - Validate message structures before sending - - -3. **Check for encoding issues** - - If using MessagePack with Go SDK, ensure data is string or byte array, not struct - - For delta encoding issues, consider disabling delta compression temporarily - - Review your data serialization approach - - -4. **Enable debug logging for detailed information** - - Turn on debug logging in your SDK to capture protocol message details - - Look for specific action types or field names mentioned in error messages - - Share logs with Ably support if the issue persists - +### 1. Update Your SDK +Check and update to the latest SDK version: +- View latest versions: https://ably.com/docs/sdks +- Check the changelog: https://changelog.ably.com/ +- Test updates in a staging environment first + + +### 2. Handle SDK-Specific Issues + +#### For Go SDK MessagePack Errors +If you see "msgpack encode error: unsupported payload type": +- Convert structs to strings before publishing: `json.Marshal(struct) → string` +- Or switch to JSON encoding instead of MessagePack +- Avoid publishing raw struct/object types directly + + +#### For Delta Encoding Failures +If you see "Failed to decode data: Decoder was not initialized with a valid base": +- The SDK will automatically trigger recovery by reattaching to the channel +- Consider disabling delta compression if issues persist +- Monitor high-throughput channels for recurring delta issues + + +### 3. Verify Message Format Compliance +- Ensure all required fields are present (especially connectionId for presence) +- Follow the protocol specification: https://sdk.ably.com/builds/ably/specification/main/protocol +- Validate message structures before sending + + +### 4. Check Network Environment +- Test from different networks to isolate network-specific issues +- Verify proxies/firewalls aren't modifying WebSocket traffic +- Try connecting directly without corporate network restrictions + + +### 5. Enable Debug Logging +Turn on debug logging to capture protocol message details: +```javascript +// JavaScript example +const ably = new Ably.Realtime({ + key: 'your-key', + logLevel: 4 // Debug level +}); +``` +Look for specific action types or field names in error messages. + ## Automatic Handling -This is a protocol error that will not be automatically retried. The connection will typically move to a failed state, requiring manual intervention to fix the underlying issue before reconnection can succeed. - +This is a protocol error that will not be automatically retried. The connection will typically move to a failed state, requiring manual intervention to fix the underlying issue before reconnection can succeed. + +**Exception**: For delta encoding failures specifically, the SDK will automatically attempt recovery by reattaching to the channel. + + ## Prevention -- Keep your SDK updated to the latest stable version -- Subscribe to Ably's release notifications for protocol updates -- Implement comprehensive error handling for protocol errors -- Test your application with various message types and formats -- Follow Ably's API documentation strictly for message formatting - +- **Keep SDKs updated**: Subscribe to Ably's release notifications +- **Validate before sending**: Check message structures match protocol requirements +- **Handle encoding properly**: + - Go SDK: Use strings/byte arrays instead of structs with MessagePack + - All SDKs: Test with various message formats +- **Implement error handling**: Add comprehensive protocol error handling +- **Monitor proactively**: Set up alerts for protocol errors +- **Test thoroughly**: Verify in various network environments + ## Related Resources -- [Protocol Documentation](https://ably.com/docs/realtime/protocol) -- [SDK Downloads](https://ably.com/download) -- [Connection State Management](https://ably.com/docs/realtime/connection) -- [Message Encoding](https://ably.com/docs/realtime/types) +- [Protocol Specification](https://sdk.ably.com/builds/ably/specification/main/protocol) +- [SDK Downloads and Versions](https://ably.com/docs/sdks) +- [Connection State Management](https://ably.com/docs/connect/states) +- [Message Types Documentation](https://ably.com/docs/api/rest-sdk/types) +- [Ably Changelog](https://changelog.ably.com/) + +## Related Errors + +• **[80000 - Connection Failed](https://help.ably.io/error/80000)** + General connection failure that may occur after unrecoverable protocol errors + +• **[80014 - Connection Timeout](https://help.ably.io/error/80014)** + Network-level timeout that may indicate similar connectivity issues preventing protocol communication + +• **[80002 - Connection Suspended](https://help.ably.io/error/80002)** + Connection state after prolonged disconnection, may require protocol re-negotiation + +• **[92001 - Encryption Configuration Error](https://help.ably.io/error/92001)** + Configuration errors that similarly require fixes rather than retries ## Need Further Help? @@ -119,6 +187,8 @@ When contacting support, please provide: - Steps to reproduce the issue - Any relevant code snippets (without sensitive credentials) - The SDK and version you're using +- Network environment details if relevant +- Debug logs showing the protocol error Our team will help you resolve this issue as quickly as possible. @@ -126,36 +196,63 @@ Our team will help you resolve this issue as quickly as possible. - + + + + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/80014-connection-timeout.mdx b/src/pages/docs/platform/errors/codes/80014-connection-timeout.mdx index a59e23946f..ebf2a690ff 100644 --- a/src/pages/docs/platform/errors/codes/80014-connection-timeout.mdx +++ b/src/pages/docs/platform/errors/codes/80014-connection-timeout.mdx @@ -1,20 +1,20 @@ - + - + # Error 80014: Connection timed out ## What Happened -Your application couldn't establish a connection to Ably within the timeout period, similar to calling someone and waiting too long without an answer. +Your application couldn't establish a connection to Ably within the timeout period, or a REST API request took too long to complete. ## Quick Reference @@ -24,9 +24,10 @@ Your application couldn't establish a connection to Ably within the timeout peri ## Quick Fix -- Check your internet connection is stable -- Verify firewall allows access to Ably endpoints -- Consider increasing timeout if on slow network +- Check your internet connection stability +- Verify firewall allows access to `*.ably.io` on ports 80 and 443 +- Increase timeout values for slow or mobile networks +- Test connection without VPN or proxy ## Error Messages @@ -34,31 +35,36 @@ You may see one of these messages: - "Unable to establish connection" - "Connecting timeout" - "Connection to Ably timed out after 10s" -- Request timeout errors from REST operations +- "request timed out" (REST operations) +- Faraday::TimeoutError (Ruby SDK specific) + + ## Common Causes -1. **Network connectivity issues** (60% of cases) +1. **Network connectivity issues** (50% of cases) - Slow or unstable internet connection - Network congestion during peak times - - Mobile network switching between towers - + - Mobile network switching between towers or poor signal + 2. **Firewall or proxy restrictions** (25% of cases) - Corporate firewalls blocking WebSocket connections - - Proxy servers adding significant overhead - - Security scanning delays in enterprise networks - - -3. **Geographic distance** (10% of cases) - - Connecting from far away from nearest Ably data center - - International connections with high latency - - -4. **Timeout configuration too strict** (5% of cases) - - Default 10-second timeout insufficient for network conditions + - Security scanning adding delays + - Proxy servers introducing connection overhead + + +3. **REST API timeouts** (15% of cases) + - Token request timeouts + - Message publishing delays + - High server load during peak usage + + +4. **Configuration issues** (10% of cases) + - Default 10-second timeout too short for network conditions - Mobile or satellite connections needing longer timeouts - + - Geographic distance from nearest Ably data center + ## Resolution Steps @@ -66,41 +72,106 @@ You may see one of these messages: - Test your internet connection stability - Try connecting from a different network - Check connection without VPN or proxy - + 2. **Check firewall configuration** - Ensure access to `*.ably.io` domains on ports 80 and 443 - Verify WebSocket connections are allowed - Test from outside corporate network to isolate firewall issues - + -3. **Adjust timeout settings for your network conditions** - - Increase `realtimeRequestTimeout` for slower networks +3. **Adjust timeout settings for your network** + - Increase `realtimeRequestTimeout` for realtime connections (default: 10 seconds) + - Increase `httpRequestTimeout` for REST operations (default: 10 seconds) - Configure appropriate timeouts for mobile applications - - See [Connection Options Documentation](https://ably.com/docs/realtime/connection#client-options) for configuration details - + - See [Connection Options Documentation](https://ably.com/docs/realtime/connection#client-options) + -4. **Monitor connection patterns** - - Track when timeouts occur most frequently - - Identify correlation with network usage or time of day - - Adjust timeout strategy based on observed patterns - +4. **Handle bursts of timeouts** + - Timeouts often occur in bursts (e.g., 4-minute windows) + - Implement circuit breaker patterns for REST operations + - Monitor for patterns in timeout occurrences + ## Automatic Handling -Ably SDKs automatically retry connection attempts after timeouts with exponential backoff. You don't need to implement your own retry logic. The SDK will: -- Retry the connection automatically +Ably SDKs automatically retry connection attempts and REST requests after timeouts with exponential backoff. You don't need to implement your own retry logic. The SDK will: +- Retry the connection or request automatically - Use progressive backoff to avoid overwhelming the network -- Eventually establish connection when network conditions improve - +- Eventually succeed when network conditions improve + + + +## Code Examples + +### Configuring Timeouts + +```javascript +// JavaScript SDK +const ably = new Ably.Realtime({ + key: 'your-api-key', + realtimeRequestTimeout: 15000, // 15 seconds for realtime connections + httpRequestTimeout: 20000 // 20 seconds for REST operations +}); +``` + + +```ruby +# Ruby SDK +client = Ably::Realtime.new( + key: 'your-api-key', + realtime_request_timeout: 15, # 15 seconds + http_request_timeout: 20 # 20 seconds +) +``` + + +### Network-Aware Configuration + +```javascript +// Adapt timeouts based on network type +const getTimeoutConfig = () => { + const connection = navigator.connection || navigator.mozConnection || navigator.webkitConnection; + + if (connection?.effectiveType === '2g' || connection?.effectiveType === 'slow-2g') { + return { + realtimeRequestTimeout: 30000, // 30 seconds for slow networks + httpRequestTimeout: 45000 // 45 seconds for REST + }; + } + + return { + realtimeRequestTimeout: 10000, // Default 10 seconds + httpRequestTimeout: 15000 // Default 15 seconds + }; +}; + +const ably = new Ably.Realtime({ + key: 'your-api-key', + ...getTimeoutConfig() +}); +``` + ## Prevention - **Configure appropriate timeouts**: Set realistic timeout values based on your users' network environment -- **Implement connection quality monitoring**: Detect network conditions and adapt behavior accordingly +- **Implement connection quality monitoring**: Detect network conditions and adapt behavior - **Design for offline scenarios**: Build your application to handle temporary disconnections gracefully - **Use regional endpoints**: Connect to the nearest Ably data center for optimal performance - +- **Monitor timeout patterns**: Track when timeouts occur to identify network or configuration issues + + + +## Performance Impact + +This error indicates failed connection attempts or REST operations that can: +- Delay realtime features activation +- Cause message publishing to fail temporarily +- Impact user experience during connection establishment +- Create bursts of errors affecting multiple operations + + ## Related Resources @@ -109,6 +180,20 @@ Ably SDKs automatically retry connection attempts after timeouts with exponentia - [Network Requirements](https://ably.com/docs/best-practice-guide#connectivity) - [Status Page](https://status.ably.com) +## Related Errors + +• **[80003 - Disconnected](https://help.ably.io/error/80003)** + Connection lost but will attempt automatic reconnection + +• **[80000 - Connection Failed](https://help.ably.io/error/80000)** + Terminal connection failure requiring manual intervention + +• **[80002 - Connection Suspended](https://help.ably.io/error/80002)** + Connection suspended after extended disconnection period + +• **[80013 - Protocol Error](https://help.ably.io/error/80013)** + Version mismatch or protocol violation that may cause connection timeouts + ## Need Further Help? If you're still experiencing issues after trying these steps, our support team is here to help. @@ -128,48 +213,64 @@ Our team will help you resolve this issue as quickly as possible. - + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/80016-operation-on-superseded-connection.mdx b/src/pages/docs/platform/errors/codes/80016-operation-on-superseded-connection.mdx index 569d6860fe..ba553b3285 100644 --- a/src/pages/docs/platform/errors/codes/80016-operation-on-superseded-connection.mdx +++ b/src/pages/docs/platform/errors/codes/80016-operation-on-superseded-connection.mdx @@ -1,11 +1,11 @@ - + @@ -36,7 +36,7 @@ You may see one of these messages: - "Operation on superseded connection" - "Error occurred during connection" - + ## Common Causes @@ -44,19 +44,19 @@ You may see one of these messages: - Normal behavior when upgrading from Comet (HTTP) to WebSocket - Old HTTP requests arrive after WebSocket connection is established - Server rejects requests for the superseded transport - + 2. **Network Transitions** (5% of cases) - Switching between WiFi and mobile data - App moving between foreground and background - Network connectivity changes - + 3. **Multiple Connections** (5% of cases) - Multiple browser tabs or app instances - Race conditions during connection attempts - Competing connections from the same client - + ## Resolution Steps @@ -64,7 +64,7 @@ You may see one of these messages: - Ably SDKs automatically manage connection supersession - The SDK will check pending state and recover transparently - No manual intervention required in most cases - + 2. **Monitor connection state** ```javascript @@ -77,19 +77,19 @@ You may see one of these messages: // Only take action if connection doesn't recover }); ``` - + 3. **Verify connection recovery** - Check if the connection state becomes `connected` - Ensure operations resume normally - Only investigate if the client never becomes connected - + 4. **If errors persist** - Check for frequent occurrences without network changes - Verify your app properly handles connection lifecycle - Ensure you're not storing and reusing old connection references - + ## Automatic Handling @@ -99,7 +99,7 @@ Ably SDKs implement sophisticated handling for this error: - Transport upgrade race conditions are managed internally - The error is not propagated to your application if recovery succeeds - + ## Prevention @@ -108,7 +108,7 @@ Ably SDKs implement sophisticated handling for this error: - **Avoid storing connection references**: Use the SDK's current connection instance - **Test network transitions**: Verify your app handles network changes gracefully - + ## Performance Impact @@ -118,14 +118,24 @@ This error has minimal performance impact: - No data loss as operations are retried on the new connection - Transparent to end users in most cases - + ## Related Resources - [Connection State Management](https://ably.com/docs/realtime/connection) - [Transport Mechanisms](https://ably.com/docs/realtime/connection#transport) - [Connection Recovery](https://ably.com/docs/realtime/connection#connection-recovery) -- Related errors: [80000](./80000-connection-failed.mdx), [80003](./80003-connection-suspended.mdx) + +## Related Errors + +• **[80000 - Connection Failed](https://help.ably.io/error/80000)** + General connection failure that may occur after supersession fails + +• **[80003 - Connection Suspended](https://help.ably.io/error/80003)** + Connection enters suspended state after prolonged disconnection + +• **[80017 - Invalid Connection ID](https://help.ably.io/error/80017)** + Related transport identification error that can occur alongside 80016 ## Need Further Help? @@ -146,16 +156,16 @@ Our team will help you resolve this issue as quickly as possible. - + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/80017-connection-closed.mdx b/src/pages/docs/platform/errors/codes/80017-connection-closed.mdx index a5a2adaa7b..c10cdd9621 100644 --- a/src/pages/docs/platform/errors/codes/80017-connection-closed.mdx +++ b/src/pages/docs/platform/errors/codes/80017-connection-closed.mdx @@ -1,16 +1,16 @@ - + -# Error 80017: Connection closed +# Error 80017: Connection Closed ## What Happened @@ -40,26 +40,26 @@ You may see one of these messages: ## Common Causes 1. **Intentional disconnect** (40% of cases) - + - Your application explicitly called `connection.close()` - App cleanup during shutdown - User-triggered disconnection 2. **Network connectivity loss** (30% of cases) - + - WiFi disconnected or unstable - Mobile signal lost - Network interface changed (WiFi to mobile data) - OS-level network offline 3. **App lifecycle events** (20% of cases) - + - Mobile app backgrounded - Browser tab unloaded - Desktop app sleep/wake cycles 4. **Operations on closed connection** (10% of cases) - + - Calling channel methods after connection closed - Attempting presence updates on closed connection - Publishing messages after closure @@ -72,14 +72,14 @@ Error 80017 often appears in logs as a normal state transition reason, not alway Connection state: closing reason: Connection closing (80017) Connection state: closed reason: Connection closed (80017) ``` - + This is only an error when you attempt to perform operations on an already closed connection. ## Resolution Steps 1. **Check connection state before operations** - + ```javascript if (ably.connection.state === 'connected') { // Safe to perform operations @@ -88,7 +88,7 @@ This is only an error when you attempt to perform operations on an already close ``` 2. **Monitor connection state changes** - + ```javascript ably.connection.on('closed', (stateChange) => { console.log('Connection closed:', stateChange.reason); @@ -97,7 +97,7 @@ This is only an error when you attempt to perform operations on an already close ``` 3. **Establish a new connection if needed** - + ```javascript // Create new Ably client instance const ably = new Ably.Realtime({ key: apiKey }); @@ -107,7 +107,7 @@ This is only an error when you attempt to perform operations on an already close ``` 4. **Implement appropriate reconnection strategy** - + - For network issues: Automatic reconnection is appropriate - For intentional closure: Only reconnect if needed - For app lifecycle: Reconnect when app becomes active @@ -115,18 +115,18 @@ This is only an error when you attempt to perform operations on an already close ## Automatic Handling Ably SDKs do not automatically reconnect after an intentional connection closure (error 80017). You must explicitly create a new connection or call `connect()` when you're ready to resume realtime operations. - + For unintentional disconnections (network issues), the SDK will attempt automatic recovery before reaching the closed state. ## Prevention - **Check connection state** before performing operations - + - **Handle app lifecycle events** properly on mobile and web platforms - + - **Implement connection monitoring** to detect and respond to closures - + - **Clean up connections** properly when no longer needed ## Platform-Specific Considerations @@ -141,18 +141,34 @@ AppState.addEventListener('change', (state) => { } }); ``` - + ### Web Applications The JavaScript SDK closes connections automatically on page unload by default (`closeOnUnload: true`). - + + +## Related Errors + +• **[80000 - Connection Failed](https://help.ably.io/error/80000)** + General connection failure that prevents establishment of a realtime connection + +• **[80002 - Connection Suspended](https://help.ably.io/error/80002)** + Connection enters suspended state after prolonged disconnection (2+ minutes) + +• **[80003 - Connection Disconnected](https://help.ably.io/error/80003)** + Temporary disconnection state before automatic reconnection attempts + +• **[80016 - Connection Blocked](https://help.ably.io/error/80016)** + Connection blocked due to exceeded limits or security restrictions + +• **[40140 - Token Expired](https://help.ably.io/error/40140)** + Authentication token expiry can trigger connection closure ## Related Resources -- [Connection state management documentation](https://ably.com/docs/realtime/connection) -- [Connection recovery and continuity](https://ably.com/docs/realtime/connection#connection-state-recovery) -- [Handling connection failures](https://ably.com/docs/best-practice-guide#handling-failures) -- Related errors: [80000](./80000-connection-failed.md), [80002](./80002-connection-suspended.md), [80003](./80003-connection-disconnected.md) +- [Connection state and recovery](https://ably.com/docs/connect/states) +- [Connection overview](https://ably.com/docs/connect/) +- [Connection API reference](https://ably.com/docs/api/realtime-sdk/connection) ## Need Further Help? @@ -173,22 +189,23 @@ Our team will help you resolve this issue as quickly as possible. - + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/80018-invalid-connection-id.mdx b/src/pages/docs/platform/errors/codes/80018-invalid-connection-id.mdx index 05536391e1..7f1dd273d5 100644 --- a/src/pages/docs/platform/errors/codes/80018-invalid-connection-id.mdx +++ b/src/pages/docs/platform/errors/codes/80018-invalid-connection-id.mdx @@ -1,116 +1,169 @@ - + - + -# Error 80018: Invalid connection ID +# Error 80018: Invalid connection ID format ## What Happened -The connection ID provided to Ably doesn't match the expected format or is invalid. +The connection ID provided to Ably doesn't match the expected format or contains invalid data that prevents proper connection management. ## Quick Reference | Error Code | HTTP Status | Category | Retryable | |------------|-------------|----------|-----------| -| 80018 | 400 | Connection Error (Authentication) | No - requires valid connection ID | +| 80018 | 400 | Connection Error (Validation) | No - requires valid connection ID format | ## Quick Fix -- Let the Ably SDK manage connection IDs automatically -- Don't manually create or modify connection IDs -- If using ably-js versions 1.2.30-1.2.33, upgrade to the latest version +- Upgrade ably-js if using versions 1.2.30-1.2.33 (known bug) +- Never manually create or modify connection IDs +- Let the Ably SDK handle all connection management automatically ## Error Messages -You may see one of these messages: +You may encounter these variations: +- "invalid connection id (invalid format)" - "Invalid connection key WHAT NODE" - "Invalid connection serial" -- "invalid connection id (invalid format)" - "invalid connectionKey: [key]. See https://help.ably.io/error/80018" +- "ConnectionManager.activateTransport: error = ErrorInfo: Invalid connection key statusCode=400 code=80018" ## Common Causes -1. **SDK bug in ably-js 1.2.30-1.2.33** (most common for SDK users) - - Known bug causing connection resume failures - - Fixed in versions after 1.2.33 - - -2. **Manually created connection IDs** (common mistake) - - Attempting to construct connection IDs instead of using SDK-provided ones - - Connection IDs must be generated by Ably, not clients - - -3. **Corrupted connection data** (less common) - - Connection ID corrupted during storage or transmission - - Network issues causing data corruption - - Truncated or incomplete connection IDs - - -4. **Invalid connection serial number** - - Connection serial is not a valid number (NaN) - - Occurs during connection state synchronization - +1. **Known SDK bug in ably-js 1.2.30-1.2.33** (most common) + - Connection resume failures due to SDK bug + - Fixed in versions 1.2.34 and later + - Affects both browser and Node.js environments + + +2. **Manual connection ID manipulation** (developer error) + - Attempting to create custom connection IDs + - Modifying SDK-provided connection IDs + - Storing and reusing old connection IDs across sessions + + +3. **Data corruption during transmission** + - Network issues causing ID corruption + - Proxy or middleware interference + - Character encoding problems + + +4. **Invalid connection serial number** (NaN values) + - Connection serial validation failures + - Often appears alongside errors 40142 and 40143 + - Can occur during connection state synchronization + + ## Resolution Steps -1. **Check your SDK version** - - If using ably-js versions 1.2.30 through 1.2.33, upgrade immediately - - This resolves the known connection resume bug - +1. **Check and upgrade your SDK version** + ```bash + # For Node.js projects + npm list ably + + # If version is 1.2.30-1.2.33, upgrade immediately + npm install ably@latest + ``` + -2. **Use SDK-managed connection IDs** +2. **Remove any manual connection ID handling** ```javascript - // ✅ Correct: Let the SDK handle connection IDs + // ❌ WRONG: Never create or modify connection IDs + const customId = 'my-connection-123'; + const modifiedId = ably.connection.id + '-modified'; + + // ✅ CORRECT: Let the SDK manage connection IDs const ably = new Ably.Realtime({ key: apiKey }); ably.connection.on('connected', () => { // Connection ID is automatically managed - console.log('Connected with ID:', ably.connection.id); + console.log('Connected:', ably.connection.id); + }); + ``` + + +3. **Establish a fresh connection** + ```javascript + // If errors persist, create a new connection + const ably = new Ably.Realtime({ + key: apiKey, + // Don't use recover option with stored IDs + // recover: null }); - // ❌ Wrong: Never manually create connection IDs - // const fakeConnectionId = 'my-connection-123'; + // Let SDK handle the entire lifecycle + ably.connection.once('connected', () => { + console.log('Fresh connection established'); + }); ``` - + -3. **Establish a new connection** - - If the error persists, establish a fresh connection - - Don't try to recover using stored connection IDs - - Let the SDK handle the entire connection lifecycle - +4. **Review connection recovery implementation** + ```javascript + // ❌ WRONG: Don't store connection IDs long-term + localStorage.setItem('connectionId', ably.connection.id); + + // ✅ CORRECT: Use recovery keys for planned handover only + // Recovery keys are valid for 2 minutes maximum + const recoveryKey = ably.connection.createRecoveryKey(); + // Use immediately in another client instance + ``` + -4. **Review your implementation** - - Remove any code that manually handles connection IDs - - Don't store connection IDs in localStorage or databases - - Don't modify SDK-provided connection IDs - +5. **Check for network interference** + - Test without proxies or VPNs if possible + - Verify data isn't being modified in transit + - Ensure proper TLS encryption is enabled + ## Automatic Handling -Ably SDKs automatically manage connection IDs and connection lifecycle. This error indicates that the automatic handling has been bypassed or a bug exists in older SDK versions. The SDK will not automatically retry this error as it requires a valid connection ID format. - +Ably SDKs are designed to manage connection IDs automatically throughout the connection lifecycle. This error indicates either: +- Manual interference with SDK-managed connection IDs +- A bug in older SDK versions (specifically ably-js 1.2.30-1.2.33) +- Data corruption preventing proper ID validation + +The SDK will not automatically retry this error as it indicates an invalid ID format that must be corrected first. + ## Prevention -- **Always use the latest SDK version** to avoid known bugs -- **Never manually create or modify connection IDs** - they have specific format requirements -- **Let the SDK manage the entire connection lifecycle** including ID generation -- **Don't persist connection IDs** across application sessions -- **Implement proper error handling** for connection operations - +- **Keep SDKs updated**: Always use the latest stable version to avoid known bugs +- **Trust SDK management**: Never manually create, modify, or persist connection IDs +- **Use proper recovery patterns**: Only use createRecoveryKey() for immediate handover (valid for 2 minutes) +- **Monitor for patterns**: If seeing this error alongside 40142/40143, investigate connection stability +- **Test thoroughly**: Verify connection handling in various network conditions + + ## Related Resources -- [Connection State Management](https://ably.com/docs/realtime/connection) +- [Connection Overview Documentation](https://ably.com/docs/connect/) +- [Connection States Documentation](https://ably.com/docs/connect/states) - [FAQ: Error Code 80018](https://faqs.ably.com/error-code-80018-invalid-connection-id-invalid-format) -- Related errors: [80023](./80023-unable-to-resume-connection.md) (connection resume failure) + +## Related Errors + +• **[80023 - Unable to Resume Connection](https://help.ably.io/error/80023)** + Often occurs when connection recovery fails after the 2-minute window + +• **[40142 - Token Request Failed](https://help.ably.io/error/40142)** + May appear alongside 80018 when authentication issues compound connection problems + +• **[40143 - Token Request Failed](https://help.ably.io/error/40143)** + Another authentication error that can occur with invalid connection attempts + +• **[80012 - Connection Closed](https://help.ably.io/error/80012)** + Previously used for some connection recovery failures, now typically shows as 80018 ## Need Further Help? @@ -132,38 +185,50 @@ Our team will help you resolve this issue as quickly as possible. + + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/80019-auth-provider-request-failed.mdx b/src/pages/docs/platform/errors/codes/80019-auth-provider-request-failed.mdx index 4947015c31..2e4676cb66 100644 --- a/src/pages/docs/platform/errors/codes/80019-auth-provider-request-failed.mdx +++ b/src/pages/docs/platform/errors/codes/80019-auth-provider-request-failed.mdx @@ -1,20 +1,20 @@ - + - + # Error 80019: Authentication provider request failed ## What Happened -Your app's authentication setup failed when trying to obtain credentials from your configured auth provider (authCallback or authUrl). +Your app failed to obtain authentication credentials from your configured auth provider (authCallback or authUrl), preventing connection to Ably. ## Quick Reference @@ -24,9 +24,9 @@ Your app's authentication setup failed when trying to obtain credentials from yo ## Quick Fix -- Check your authCallback or authUrl is working correctly -- Verify the auth response format matches Ably's requirements -- Test your auth endpoint independently to ensure it returns valid credentials +- Verify your authCallback or authUrl is working correctly +- Check the error's `cause` field for specific failure details +- Test your auth endpoint independently to ensure valid responses ## Error Messages @@ -36,42 +36,46 @@ You may see one of these messages: - "authCallback failed with an exception" - "authUrl failed with an exception" - "Empty response received from authUrl" +- "auth_callback raised an exception" (Python) - "timed out" (iOS/macOS) ## Common Causes 1. **Auth callback throwing exceptions** (40% of cases) - Unhandled errors in your authCallback function - - Wrong return type from callback (e.g., returning object instead of dict in Python) + - Wrong return type (e.g., returning object instead of dict in Python) - Missing error handling in callback code - + 2. **Auth URL returning errors** (30% of cases) - Auth server returning 4xx or 5xx status codes - Network connectivity issues reaching auth server - Auth server down or misconfigured - + 3. **Empty or malformed auth response** (20% of cases) - Auth provider returning null or empty response - Invalid JSON format in response - Missing required fields (token, expires, capability) - + -4. **Serialization issues** (10% of cases) - - Problems serializing capability field in .NET - - JSON parsing errors with auth response - +4. **Network timeouts** (10% of cases) + - Auth request timing out (especially on mobile) + - Slow auth server response + - Network latency issues + ## Resolution Steps 1. **Check the error's cause field** + - The 80019 error includes a `cause` field with the underlying error - This reveals the specific problem with your auth provider - + - Check console logs or error details for this information 2. **For authCallback errors** - - Add proper error handling to your callback: + + - Add comprehensive error handling to your callback: ```javascript authCallback: function(tokenParams, callback) { try { @@ -84,51 +88,94 @@ You may see one of these messages: } } ``` - - - Ensure you're returning the correct type (dict/object as expected by SDK) - - For debugging, use authCallback instead of authUrl for better visibility - + + + - Ensure you're returning the correct type for your SDK: + - JavaScript: Object with token details + - Python: Dictionary (not TokenDetails object) + - .NET: Use CreateTokenRequestAsync instead of CreateTokenRequestObjectAsync + 3. **For authUrl errors** - - Test your auth URL directly with curl or a browser - - Verify it returns valid JSON with required fields: + + - Test your auth URL directly using curl or Postman + - Verify it returns valid JSON with all required fields: ```json { - "token": "your-jwt-token", + "token": "your-jwt-token-or-token-string", "expires": 1234567890000, "capability": {"*": ["*"]} } ``` - + + - Check server logs for errors - - Ensure the endpoint is accessible from your app + - Ensure the endpoint is accessible from your application + - Verify CORS settings if calling from browser 4. **For 403 responses** + - This indicates a permanent authentication failure - - The connection will move to "failed" state and won't retry - - Fix the authentication issue on your server before reconnecting - - -5. **For .NET serialization issues** - - Use `CreateTokenRequestAsync` instead of `CreateTokenRequestObjectAsync` - - Ensure capability field is properly formatted - + - Connection will move to "failed" state and won't retry automatically + - Fix the authentication issue on your server: + - Check user permissions + - Verify API key validity + - Review auth server logic + +5. **For timeout errors** + + - Increase timeout settings if possible + - Optimize auth server response time + - Consider using authCallback instead of authUrl for better control + - Check network connectivity and latency + +6. **For debugging** + + - Enable verbose logging in your Ably client + - Use authCallback instead of authUrl for better visibility + - Test auth provider independently before integrating with Ably + - Log all auth attempts and responses (excluding sensitive data) ## Automatic Handling - **403 errors**: Connection moves to "failed" state (permanent failure, no automatic retry) - **401/other errors**: Connection moves to "disconnected" state (SDK will retry with backoff) +- **500 errors**: Treated as server errors (SDK retries with backoff) - **Timeout errors**: Behavior varies by SDK (failed or disconnected state) - + ## Prevention -- Implement robust error handling in auth callbacks +- Implement robust error handling in all auth callbacks - Validate auth responses before returning them - Set reasonable timeouts for auth requests - Monitor your auth server health and availability - Test authentication under various network conditions - +- Use try-catch blocks around auth logic +- Log auth failures for debugging (without sensitive data) + + +## Performance Impact + +This error prevents all realtime functionality: +- No connection can be established +- All channels remain unattached +- No messages can be sent or received +- Presence features are unavailable + +## Related Errors + +• **[40170 - Error from client token callback](https://help.ably.io/error/40170)** + Often appears alongside 80019 when the auth callback itself throws an exception + +• **[40101 - Invalid API key](https://help.ably.io/error/40101)** + May occur if auth provider returns invalid credentials + +• **[40102 - Token expired](https://help.ably.io/error/40102)** + Can happen if auth provider returns already-expired tokens + +• **[80000 - Connection failed](https://help.ably.io/error/80000)** + Generic connection failure that may result from persistent auth issues ## Related Resources @@ -136,7 +183,7 @@ You may see one of these messages: - [Token authentication guide](https://ably.com/docs/auth/token) - [authCallback documentation](https://ably.com/docs/auth/token#auth-callback) - [authUrl documentation](https://ably.com/docs/auth/token#auth-url) -- Related errors: [40170](./40170-error-from-client-token-callback.md) (often appears alongside 80019) +- [Connection states explained](https://ably.com/docs/realtime/connection#connection-states) ## Need Further Help? @@ -157,11 +204,11 @@ Our team will help you resolve this issue as quickly as possible. - @@ -171,30 +218,38 @@ Our team will help you resolve this issue as quickly as possible. - Recommendations Source: - Error handling pattern from knowledge file lines 54-66 - Auth URL validation from knowledge file lines 68-76 - - Debugging tips from knowledge file lines 115-119 -- Code Examples Rationale: Included error handling example as it's essential for resolution (from knowledge file) + - Debugging tips from knowledge file lines 115-119 and 178-181 + - Prevention strategies from knowledge file lines 85-104 +- Code Examples Rationale: + - Error handling example included as essential for resolution (knowledge file lines 55-65) + - Auth response format included as required for validation (knowledge file lines 70-75) --> + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/80023-unable-to-resume-connection-from-another-site.mdx b/src/pages/docs/platform/errors/codes/80023-unable-to-resume-connection-from-another-site.mdx index 8c45b2fd19..f0200d2a3f 100644 --- a/src/pages/docs/platform/errors/codes/80023-unable-to-resume-connection-from-another-site.mdx +++ b/src/pages/docs/platform/errors/codes/80023-unable-to-resume-connection-from-another-site.mdx @@ -1,146 +1,187 @@ - + - + # Error 80023: Unable to resume connection from another site ## What Happened -Your app tried to resume a connection at a different Ably data center than where it was originally established, which is not supported for consistency and performance reasons. +Your connection attempted to resume at a different Ably data center than where it was originally established, which is not supported to maintain message ordering and presence consistency. ## Quick Reference | Error Code | HTTP Status | Category | Retryable | |------------|-------------|----------|-----------| -| 80023 | 400 | Connection (Resume) | No - requires new connection | +| 80023 | 400 | Connection (Resume) | No - requires fresh connection | ## Quick Fix -- Let the SDK establish a fresh connection automatically -- Don't try to force resumption - the SDK handles this -- Re-attach to channels after the new connection is established +- Allow the SDK to establish a fresh connection automatically +- Don't implement manual retry logic - it's handled for you +- Re-attach to channels after the new connection establishes +- Use history to retrieve any messages sent during disconnection ## Error Messages -You may see this message: +You'll see this message: - "Unable to resume connection from another site" ## Common Causes 1. **Geographic movement** (40% of cases) - - - You or your users physically moved to a different region - - Mobile users traveling between countries - - Device switching between WiFi and cellular networks + + - Users physically moving between regions + - Mobile devices traveling between countries + - Switching between WiFi and cellular networks in different locations 2. **Network routing changes** (35% of cases) - - - ISP routing changes directing traffic to different data center - - VPN connection changes or switching locations - - Corporate network policy updates - -3. **Fallback host connection** (25% of cases) - - - Primary endpoint fails and client connects to fallback host - - Load balancer redirects to different site - - DNS changes pointing to different Ably region + + - ISP routing updates directing traffic to different data centers + - VPN location changes or switching between VPN servers + - Corporate network policy updates affecting routing + +3. **Fallback host connection** (20% of cases) + + - Primary endpoint failure causing connection to fallback host + - Load balancer redirecting to different regional site + - DNS resolution changes pointing to alternate Ably region + +4. **Connection overlap scenarios** (5% of cases) + + - TCP connection breaks where endpoints don't notice simultaneously + - Client connects to fallback before primary notices disconnection + - Can cause temporary presence state inconsistencies ## Resolution Steps 1. **Allow automatic recovery** - - - The SDK will automatically establish a new connection - - Don't implement manual retry logic - it's handled for you - - Wait for the connection state to become `connected` - -2. **Re-establish channel state** - - - Channels will need to be re-attached - - Presence state will be re-entered automatically - - Channel continuity may be lost - retrieve missed messages using history if needed - -3. **Handle in your application** - + + - The SDK automatically establishes a new connection at the optimal site + - Connection state will transition through `connecting` to `connected` + - No manual intervention required - avoid implementing retry logic + +2. **Monitor connection state changes** + ```javascript ably.connection.on('connected', (stateChange) => { if (stateChange.reason?.code === 80023) { // Connection established at new site - // Re-initialize any local state if needed console.log('Connection resumed at new location'); + // Re-initialize any local state if needed } }); ``` - + + +3. **Re-establish channel state** + + - Channels automatically re-attach after new connection + - Presence state re-enters automatically for present members + - Channel continuity may be lost - use history for missed messages -4. **Retrieve missed messages if needed** - - - Use channel history to get any messages sent during disconnection - - See [History documentation](https://ably.com/docs/storage-history/history) +4. **Retrieve missed messages** + + ```javascript + // After reconnection, get messages from disconnection period + const history = await channel.history({ + limit: 100, + direction: 'backwards' + }); + history.items.forEach(message => { + // Process any missed messages + processMessage(message); + }); + ``` + ## Automatic Handling Ably SDKs automatically handle this error by: - -- Establishing a fresh connection at the optimal site -- Re-attaching to channels automatically -- Maintaining message ordering within the new connection -- Preserving your authentication credentials + +- Establishing a fresh connection at the geographically optimal site +- Re-attaching to all previously attached channels +- Maintaining message ordering within the new connection session +- Preserving authentication credentials and capabilities +- Re-entering presence sets for members who were present ## Prevention -To minimize the impact of cross-site connection changes: - -1. **Design for stateless connections** - +### Design for connection mobility + +1. **Implement stateless connections** - Don't rely on persistent server-side connection state - - Store critical state client-side where appropriate - - Design your app to handle connection interruptions gracefully + - Store critical application state client-side + - Design for transparent connection migrations -2. **Implement robust reconnection handling** - - - Monitor connection state changes - - Handle channel re-attachment transparently - - Provide appropriate UI feedback during reconnection +2. **Handle presence carefully** + + - For time-critical presence updates, consider reducing `remainPresentFor` parameter + - Default is 15 seconds; can be reduced to as low as 1 second + - Adjust `heartbeatInterval` accordingly for faster presence synchronization 3. **Test geographic scenarios** - - - Test with VPN location changes - - Simulate network provider switches - - Verify behavior when moving between regions - -## Why This Error Exists - -This error protects important system guarantees: - -- **Message ordering**: Ensures messages remain in correct sequence -- **Presence consistency**: Maintains accurate member state -- **Performance optimization**: Routes you to the nearest data center -- **Data locality**: Respects regional data requirements - -## Mobile Considerations - -Mobile applications are particularly affected because: - -- Users physically move between regions -- Network switching (WiFi to cellular) can change routing + + - Test with VPN location changes during active connections + - Simulate network provider switches (WiFi to cellular) + - Verify application behavior when users move between regions + +## Why This Protection Exists + +This error maintains critical system guarantees: + +- **Message ordering**: Ensures messages remain in correct sequence within channels +- **Presence consistency**: Prevents duplicate presence entries and maintains accurate member state +- **Performance optimization**: Routes connections to the nearest data center for lowest latency +- **Data locality**: Respects regional data residency requirements +- **System integrity**: Prevents complex cross-site synchronization issues + +As noted in the implementation: "Cross-site resumes mess up presence invariants, and you can't get channel continuity anyway" + + +## Mobile and Network Considerations + +### Mobile applications + +Mobile apps are particularly affected because: +- Users physically move between geographic regions +- Network switching (WiFi to cellular) changes routing paths - Apps backgrounded in one location may resume in another -- Mobile networks can change routing unexpectedly +- Mobile networks can unexpectedly change routing policies + +### Network infrastructure + +This error is normal and expected during: +- Users traveling between countries or regions +- ISP infrastructure maintenance or updates +- Corporate network policy changes +- Cloud provider routing updates +- VPN server switches or location changes ## Related Resources -- [Ably Global Infrastructure](https://ably.com/docs/general/global) -- [Connection State Management](https://ably.com/docs/realtime/connection) -- [Channel History](https://ably.com/docs/storage-history/history) +- [Ably Edge Network](https://ably.com/docs/platform/architecture/edge-network) +- [Connection States](https://ably.com/docs/connect/states) +- [History and Message Retrieval](https://ably.com/docs/storage-history/history) - [FAQ: Error Code 80023](https://faqs.ably.com/error-code-80023-unable-to-resume-connection-from-a-different-site) -- Related errors: [80002](https://ably.com/docs/errors/80002), [80018](https://ably.com/docs/errors/80018) + +## Related Errors + +• **[80002 - Connection Suspended](https://help.ably.io/error/80002)** + Connection enters suspended state after prolonged disconnection + +• **[80018 - Invalid Connection Key](https://help.ably.io/error/80018)** + Connection key validation failure for broader reasons + +• **[40006 - Malformed Connection Key](https://help.ably.io/error/40006)** + Connection key format issues preventing validation ## Need Further Help? @@ -161,40 +202,70 @@ Our team will help you resolve this issue as quickly as possible. - + + + + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/90000-channel-operation-failed.mdx b/src/pages/docs/platform/errors/codes/90000-channel-operation-failed.mdx index 0df935b53f..6dce39e94e 100644 --- a/src/pages/docs/platform/errors/codes/90000-channel-operation-failed.mdx +++ b/src/pages/docs/platform/errors/codes/90000-channel-operation-failed.mdx @@ -1,13 +1,13 @@ - + - + # Error 90000: Channel operation failed @@ -27,6 +27,7 @@ A channel operation couldn't be completed due to conflicting requests, invalid s - Ensure sequential channel operations (await attach before detach) - Check channel state before operations - Implement debouncing for rapid DOM manipulation scenarios +- Monitor connection state to ensure it's active ## Error Messages @@ -37,31 +38,37 @@ You may see one of these messages: - "Unable to attach; reason unknown; state = {state}" - "Unable to detach; reason unknown; state = {state}" - "Can't attach when not in an active state" +- "Can't detach when not in an active state" - "Channel state is failed" - "channel is being DETACHED" +- "Unable to satisfy channel request internal error" ## Common Causes - + 1. **Race conditions between attach/detach** (60% of cases) - Calling detach() while attach() is pending - Calling attach() while detach() is pending - Rapid DOM manipulation triggering multiple operations + - Fast scrolling with dynamic elements (commonly reported by Front customers) 2. **Invalid channel or connection state** (30% of cases) - Attempting operations on failed channels - Operations when connection isn't active - Channel already in detaching state + - Connection in suspended or failed state -3. **Unknown attachment failures** (10% of cases) +3. **Channel request failures** (10% of cases) + - Server unable to satisfy channel request - Connection issues during attachment - Internal server errors - Timeout during channel operations + - Missing client ID for presence operations ## Resolution Steps 1. **For attach/detach conflicts** - + - Wait for current operation to complete: ```javascript // Ensure sequential operations @@ -69,28 +76,35 @@ You may see one of these messages: await channel.attach(); ``` - Never call conflicting operations simultaneously + -2. **For rapid DOM manipulation** - +2. **For rapid DOM manipulation scenarios** + - Implement debouncing to reduce operation frequency: ```javascript const debouncedAttach = debounce(() => { channel.attach(); }, 300); ``` + - This pattern is especially important for scrolling interfaces with dynamic elements 3. **For state-related errors** - + - Check channel state before operations: ```javascript if (channel.state === 'attached') { channel.publish('event', data); } ``` - - Monitor connection state to ensure it's active + - Monitor connection state to ensure it's active: + ```javascript + if (ably.connection.state === 'connected') { + // Safe to perform channel operations + } + ``` 4. **For persistent failures** - + - Implement retry with exponential backoff (only for this specific error): ```javascript channel.attach((err) => { @@ -100,40 +114,65 @@ You may see one of these messages: }); ``` +5. **For production chat systems** + + - Monitor for "unable to satisfy channel request" messages + - Check server logs for subscribe errors + - Verify chat message channel configuration + ## Automatic Handling - + Ably SDKs do not automatically retry error 90000. This is an application-level error requiring: - Proper sequencing of channel operations - State validation before operations - Manual retry logic with appropriate delays -Note: Based on internal discussions, channels often remain functional despite this error appearing in logs. +**Important**: Based on production experience and support team reports, channels often remain functional despite this error appearing in logs. The error typically indicates a timing issue rather than a complete failure. ## Prevention - + - **Sequential Operations**: Always await channel operations to complete - **State Management**: Track channel state in your application -- **Debouncing**: Implement delays for high-frequency scenarios +- **Debouncing**: Implement delays for high-frequency scenarios (300ms recommended) - **Error Boundaries**: Handle errors gracefully without disrupting user experience +- **Connection Monitoring**: Check connection state before channel operations +- **Lifecycle Management**: Properly manage channel lifecycle in component mount/unmount ## SDK Implementation Variations - + Different Ably SDKs may return different HTTP status codes with error 90000: - **JavaScript**: 409 for conflicts, 500 for unknown errors, 400 for generic failures - **iOS/macOS**: Consistently uses 500 - **Python**: 409 for conflicts - **Java**: 400 for state failures - **Go**: No explicit status code +- **.NET**: Status code varies by context + +## Known Issues + + +**Specification Compliance (RTL4h)**: The current behavior in ably-js may not fully comply with specification RTL4h, which states that attach operations should wait for pending requests to complete rather than error immediately. This behavior is unique to ably-js and possibly ably-python. Engineering teams are aware of this inconsistency. ## Related Resources -- [Channel lifecycle documentation](https://ably.com/docs/channels#lifecycle) +- [Channel state documentation](https://ably.com/docs/realtime/channels) - [Connection state management](https://ably.com/docs/realtime/connection) -- [Channel attach/detach best practices](https://ably.com/docs/best-practice#channel-lifecycle) -- Related errors: [80000](https://ably.com/docs/errors/80000) (Connection Failed) +- [Error handling best practices](https://ably.com/docs/best-practice#error-handling) +- [GitHub Issue #2056](https://github.com/ably/ably-js/issues/2056) - Community discussion on error handling + +## Related Errors + +• **[80000 - Connection Failed](https://help.ably.io/error/80000)** + Connection failures that can prevent channel operations from succeeding + +• **[80002 - Connection Suspended](https://help.ably.io/error/80002)** + Connection suspended state prevents channel operations after extended disconnection + +• **[91000 - Unable to Enter Presence](https://help.ably.io/error/91000)** + Channel presence operations that fail due to missing client ID or state issues ## Need Further Help? @@ -155,43 +194,59 @@ Our team will help you resolve this issue as quickly as possible. + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/90001-channel-operation-failed-invalid-state.mdx b/src/pages/docs/platform/errors/codes/90001-channel-operation-failed-invalid-state.mdx index 93cf06d352..888fe44088 100644 --- a/src/pages/docs/platform/errors/codes/90001-channel-operation-failed-invalid-state.mdx +++ b/src/pages/docs/platform/errors/codes/90001-channel-operation-failed-invalid-state.mdx @@ -1,13 +1,13 @@ - + - + # Error 90001: Channel operation failed (invalid channel state) @@ -37,6 +37,7 @@ You may see one of these messages: - "Unable to {action} presence channel while in {state} state" - "Channel not attached" - "attempted to subscribe while channel is in Failed state" +- "Unable to enter/leave/update presence channel (incompatible state)" The `{state}` placeholder shows the current channel state, and `{action}` shows the operation you attempted. @@ -46,34 +47,35 @@ The `{state}` placeholder shows the current channel state, and `{action}` shows - Attempting to publish messages before the channel is attached - Not waiting for attachment confirmation - Racing between channel creation and first operation - + 2. **Operating on failed channels** (25% of cases) - Trying to use a channel after it entered `failed` state - Not resetting failed channels before reuse - Attempting to detach an already failed channel - + 3. **Presence operations in wrong state** (10% of cases) - Entering presence when channel isn't attached - Leaving presence during detaching - Getting presence members on failed channels - + 4. **Device wake/sleep issues** (5% of cases) - Operations attempted after device wakes from sleep - Network not ready when SDK attempts operations - Channels in unexpected states after wake - + - Common on mobile devices and laptops with sleep mode + ## Resolution Steps 1. **Check current channel state** ```javascript console.log('Channel state:', channel.state); - // States: initialized, attaching, attached, detaching, detached, failed + // States: initialized, attaching, attached, detaching, detached, failed, suspended ``` - + 2. **Wait for channel attachment before operations** ```javascript @@ -87,7 +89,7 @@ The `{state}` placeholder shows the current channel state, and `{action}` shows channel.publish('message', 'data'); }); ``` - + 3. **Handle failed channels by resetting them** ```javascript @@ -108,7 +110,7 @@ The `{state}` placeholder shows the current channel state, and `{action}` shows }); } ``` - + 4. **Use state change listeners for robust operation timing** ```javascript @@ -123,10 +125,11 @@ The `{state}` placeholder shows the current channel state, and `{action}` shows console.log('State changed from', stateChange.previous, 'to', stateChange.current); if (stateChange.current === 'failed') { // Handle failure - perhaps notify user or attempt recovery + console.error('Channel failed:', stateChange.reason); } }); ``` - + 5. **For presence operations, ensure attachment first** ```javascript @@ -141,12 +144,33 @@ The `{state}` placeholder shows the current channel state, and `{action}` shows } }); ``` - + + +6. **Handle device sleep/wake scenarios** + ```javascript + // Monitor visibility changes (browser) or app state (mobile) + document.addEventListener('visibilitychange', () => { + if (!document.hidden) { + // Device woke up, check channel states + Object.values(ably.channels.all).forEach(channel => { + if (channel.state === 'suspended' || channel.state === 'failed') { + // Reset the channel + channel.detach(() => channel.attach()); + } + }); + } + }); + ``` + ## Automatic Handling -Ably SDKs do not automatically retry this error because it indicates a state machine violation that requires explicit correction. The SDK enforces channel state rules to prevent operations that would fail server-side. - +Ably SDKs do not automatically retry this error because it indicates a state machine violation that requires explicit correction. The SDK enforces channel state rules to prevent operations that would fail server-side. However, the SDKs will automatically: + +- Queue messages during `attaching` state (with default settings) +- Reattach suspended channels when connection is restored +- Emit state change events you can listen to for recovery + ## Prevention @@ -155,14 +179,41 @@ Ably SDKs do not automatically retry this error because it indicates a state mac - **Implement state change listeners** to coordinate operations - **Handle device sleep/wake scenarios** explicitly in mobile apps - **Test channel failure scenarios** during development - +- **Monitor state transitions** proactively in production +- **Implement proper error recovery** for failed channels + + +## Performance Impact + +This error prevents the specific operation but doesn't affect: +- Other channels in your application +- The underlying connection (unless connection itself failed) +- Message history already stored +- Other clients subscribed to the same channel ## Related Resources -- [Channel States Documentation](https://ably.com/docs/channels#channel-states) +- [Channel States Documentation](https://ably.com/docs/channels/states) - [Connection State Recovery](https://ably.com/docs/connect/states) -- [Presence Documentation](https://ably.com/docs/presence) -- Related errors: [90000](https://help.ably.io/error/90000), [90002](https://help.ably.io/error/90002), [90003](https://help.ably.io/error/90003) +- [Presence Documentation](https://ably.com/docs/realtime/presence) +- [Channel Options and Settings](https://ably.com/docs/channels) + +## Related Errors + +• **[90000 - Generic Channel Operation Failed](https://help.ably.io/error/90000)** + Generic channel operation error, often with similar state-related causes + +• **[90002 - Channel Operation Failed (Epoch Expired)](https://help.ably.io/error/90002)** + Channel epoch issues that may require similar recovery patterns + +• **[90003 - Unable to Recover Channel](https://help.ably.io/error/90003)** + Channel recovery failures that may lead to failed state requiring reset + +• **[80002 - Connection Suspended](https://help.ably.io/error/80002)** + Connection suspension that can cause channels to enter suspended state + +• **[91001 - Unable to Enter Presence](https://help.ably.io/error/91001)** + Specific presence errors often related to channel state issues ## Need Further Help? @@ -176,6 +227,7 @@ When contacting support, please provide: - Steps to reproduce the issue - Any relevant code snippets (without sensitive credentials) - The SDK and version you're using +- Whether the error occurs after device sleep/wake cycles Our team will help you resolve this issue as quickly as possible. @@ -183,53 +235,68 @@ Our team will help you resolve this issue as quickly as possible. - + + + @@ -238,6 +305,6 @@ To improve this error code documentation: 1. First approach: Update editorial-notes.md in ably-os repository with specific guidance for error 90001 2. Regenerate: Run `./bin/ably-os errors document-error-codes 90001 --force` 3. For broader improvements: Review and update ably-os prompt templates -4. Context: See https://github.com/ably/ably-os/blob/main/docs/ERROR_COMMANDS_GUIDE.md +4. Context: See https://github.com/ably/ably-os/blob/5f4ba43/docs/ERROR_COMMANDS_GUIDE.md 5. Source repository: https://github.com/ably/ably-os --> \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/90003-unable-to-recover-channel-messages-expired.mdx b/src/pages/docs/platform/errors/codes/90003-unable-to-recover-channel-messages-expired.mdx index f89f9cf34e..6a69cbc58d 100644 --- a/src/pages/docs/platform/errors/codes/90003-unable-to-recover-channel-messages-expired.mdx +++ b/src/pages/docs/platform/errors/codes/90003-unable-to-recover-channel-messages-expired.mdx @@ -1,13 +1,13 @@ - + - + # Error 90003: Unable to recover channel (messages expired) @@ -33,7 +33,7 @@ Your app attempted to recover a channel after disconnection, but the messages ne You may see this error message: - "Unable to recover channel (messages expired)" -This appears as a non-fatal error during channel attachment when recovery fails. +This appears as a non-fatal error during channel attachment when recovery fails. The error is marked as non-fatal, meaning your connection remains viable and the channel can still attach without recovery. ## Common Causes @@ -41,21 +41,25 @@ This appears as a non-fatal error during channel attachment when recovery fails. - Your app was offline longer than your message retention period - Common with mobile apps that are backgrounded for extended periods - Network outages lasting beyond retention limits + 2. **High message volume** (25% of cases) - - Too many messages published while disconnected + - Too many messages published while disconnected (> 100 messages per channel for SSE connections) - Message buffer exceeded storage limits - High-traffic channels with limited retention + 3. **Account retention limits** (10% of cases) - Free accounts: 2-minute retention period + - Paid accounts: 24-72 hours depending on plan - Messages expired based on your plan's limits - - Time-based expiry policies + -4. **Regional sync issues** (5% of cases) +4. **Regional sync issues or instance recycling** (5% of cases) - Rare cases of messages not syncing between regions - Instance recycling during disconnection - System maintenance affecting message availability + ## Resolution Steps @@ -63,7 +67,7 @@ This appears as a non-fatal error during channel attachment when recovery fails. - The channel will attach successfully but without historical messages - Your app will start receiving messages from the current point - This is a non-fatal error - the connection remains viable - + 2. **Handle the message gap in your application** ```javascript @@ -76,28 +80,66 @@ This appears as a non-fatal error during channel attachment when recovery fails. } }); ``` - + 3. **Implement state synchronization if needed** - Request current state from your backend - Use a separate state channel for critical data + - Consider using presence for state tracking - Don't rely solely on message history for state recovery - + 4. **Review your retention requirements** - Check your current plan's retention limits at [Ably Dashboard](https://ably.com/dashboard) - Consider upgrading if you need longer retention periods - Monitor disconnection patterns in your application - + - For SSE connections, be aware of the 2-minute or 100-message limit + ## Automatic Handling Ably SDKs handle this error automatically: -- The error is marked as non-fatal, so the connection remains active +- The error is marked as non-fatal (fourth parameter `true` in ErrorInfo constructor) +- The connection remains active and usable - The channel will attach successfully without recovery - New messages will be received normally from the current point - No automatic retry is performed as the messages are permanently expired - + + +## Code Examples + +### Handling Recovery Failure in JavaScript +```javascript +// Monitor channel state changes for recovery issues +channel.on('attached', (stateChange) => { + if (stateChange.reason?.code === 90003) { + // Recovery failed due to expired messages + console.warn('Channel attached without recovery - messages expired'); + + // Option 1: Notify the user + showNotification('Some messages may have been missed while offline'); + + // Option 2: Request state sync + requestStateFromBackend(); + + // Option 3: For SSE connections, consider fallback + if (connectionType === 'sse') { + // SSE has stricter limits (2 min or 100 messages) + handleSSERecoveryFailure(); + } + } +}); + +// For applications requiring message continuity +function handleMessageGap() { + // Don't try to recover expired messages + // Instead, rebuild state from other sources + return fetchCurrentStateFromAPI() + .then(state => updateLocalState(state)) + .catch(err => console.error('State sync failed:', err)); +} +``` + ## Prevention @@ -106,7 +148,8 @@ Ably SDKs handle this error automatically: - **Use appropriate retention**: Choose an Ably plan that matches your recovery window needs - **Implement state channels**: Use dedicated channels for critical state that must survive disconnections - **Monitor connection health**: Track disconnection duration and patterns - +- **For SSE connections**: Be aware of the 2-minute timeout and 100-message limit + ## Mobile Considerations @@ -120,15 +163,47 @@ Consider implementing: - Push notifications to wake the app for critical updates - Local state caching for offline scenarios - User notifications when message gaps occur - +- Presence tracking to detect when users return online + + +## Technical Context + +### How Recovery Works +When a client reconnects, it provides a `channelSerial` to indicate the last message it received. The server attempts to replay messages from that point. Error 90003 occurs when: +- The requested `channelSerial` no longer exists in the message cache +- The `HistoryResponseType` is `Expired` or `Unknown` +- Messages corresponding to the given channelSerial have been removed + + +### Message Retention Limits +| Account Type | Retention Period | +|--------------|------------------| +| Free | 2 minutes | +| Paid Standard | 24 hours | +| Paid Pro | 72 hours | +| Enterprise | Configurable | + +Note: High message volumes may cause earlier expiry regardless of time limits. + ## Related Resources -- [Channel recovery and resume documentation](https://ably.com/docs/realtime/channels#nonfatal-errors) -- [Message history and retention](https://ably.com/docs/general/history) -- [Connection state recovery](https://ably.com/docs/realtime/connection#connection-state-recovery) +- [Channel recovery and resume documentation](https://ably.com/docs) +- [Message history and retention](https://ably.com/docs) +- [Connection state recovery](https://ably.com/docs) - [Ably pricing and retention limits](https://ably.com/pricing) -- Related error: [90004 - Message limit exceeded](https://help.ably.io/error/90004) +- [FAQ: Error 90003](https://faqs.ably.com/error-code-90003-unable-to-recover-channel-messages-expired) + +## Related Errors + +• **[90004 - Message limit exceeded](https://help.ably.io/error/90004)** + Similar recovery failure but due to message count limits rather than time-based expiry + +• **[80002 - Connection suspended](https://help.ably.io/error/80002)** + Connection state that often precedes recovery attempts after extended disconnection + +• **[80003 - Connection disconnected](https://help.ably.io/error/80003)** + Temporary disconnection state where recovery is still possible if within retention limits ## Need Further Help? @@ -149,42 +224,53 @@ Our team will help you resolve this issue as quickly as possible. - + + + @@ -193,6 +279,6 @@ To improve this error code documentation: 1. First approach: Update editorial-notes.md in ably-os repository with specific guidance for error 90003 2. Regenerate: Run `./bin/ably-os errors document-error-codes 90003 --force` 3. For broader improvements: Review and update ably-os prompt templates -4. Context: See https://github.com/ably/ably-os/blob/main/docs/ERROR_COMMANDS_GUIDE.md +4. Context: See https://github.com/ably/ably-os/blob/5f4ba43/docs/ERROR_COMMANDS_GUIDE.md 5. Source repository: https://github.com/ably/ably-os --> \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/90004-message-limit-exceeded.mdx b/src/pages/docs/platform/errors/codes/90004-message-limit-exceeded.mdx index cf194a900b..e4aa175ef8 100644 --- a/src/pages/docs/platform/errors/codes/90004-message-limit-exceeded.mdx +++ b/src/pages/docs/platform/errors/codes/90004-message-limit-exceeded.mdx @@ -1,13 +1,13 @@ - + - + # Error 90004: Message Limit Exceeded @@ -27,6 +27,7 @@ Your channel couldn't recover all missed messages because the number of messages - Channel remains functional with partial message recovery - Use the History API to retrieve messages beyond the recovery limit - Reduce rewind parameters to request fewer messages +- Check the `resumed` flag to detect message gaps ## Error Messages @@ -34,33 +35,37 @@ You may see one of these messages: - "Unable to recover channel (message limit exceeded)" - "Channel message limit exceeded [number] bytes" (Ruby SDK specific) +In your logs, you might see: +- `error=e: Unable to recover channel message limit exceeded statusCode=404 code=90004` +- `channelSerial=[value] error=message:Unable to recover channel message limit exceeded,code:90004,statusCode:404,nonfatal:true` + ## Common Causes 1. **Long disconnection period** (60% of cases) - - Client disconnected for extended time + - Client disconnected for extended time (typically >2 minutes) - More messages accumulated than recovery limit allows - - Example: 20 messages/second × 50 seconds = 1000 messages, but only 100-1000 recoverable - + - Example: 20 messages/second × 50 seconds = 1000 messages, but only 100-1000 recoverable depending on configuration + 2. **Large rewind parameter** (30% of cases) - - Requesting rewind with too many messages - - Rewind timeframe contains more than 100 messages + - Requesting rewind with more than 100 messages + - Rewind timeframe contains excessive messages - Channel has high message volume in requested period - + 3. **High-volume channels** (10% of cases) - - Channels with rapid message rates + - Channels with rapid message rates (>20 messages/second) - Brief disconnections on busy channels - Message cache fills quickly during recovery attempt - + ## Resolution Steps 1. **Continue with partial recovery** - This is a non-fatal error - your channel remains operational - - The connection is active with the most recent messages available - - The `resumed` flag will be `false` indicating a message gap - + - The connection is active with the most recent messages available (up to 100-1000 messages) + - The `resumed` flag will be `false` indicating a message gap exists + 2. **Retrieve missing messages via History API** ```javascript @@ -76,13 +81,14 @@ You may see one of these messages: processMessage(message); }); ``` - + 3. **Adjust recovery parameters** - - For rewind, use smaller time windows or message counts + - For rewind, use values under 100 messages (e.g., `rewind=50`) + - Use time-based rewind with limits: `rewind=30s&rewindLimit=50` - Consider implementing pagination for large message sets - Monitor channel message rates to set appropriate limits - + 4. **Implement message continuity handling** ```javascript @@ -90,33 +96,81 @@ You may see one of these messages: if (!stateChange.resumed) { // Message continuity lost - fetch missing messages console.log('Channel attached but message continuity lost'); - fetchMissingMessages(); + + // Use History API to fill the gap + fetchMissingMessages(stateChange.reason); } }); + + async function fetchMissingMessages(errorInfo) { + if (errorInfo && errorInfo.code === 90004) { + // Messages exceeded limit - retrieve via History + const history = await channel.history({ limit: 1000 }); + // Process messages... + } + } ``` - + ## Automatic Handling Ably SDKs treat this as a non-fatal error: - Channel attachment proceeds despite the error - Connection remains active and functional -- Most recent messages (up to limit) are delivered +- Most recent messages (up to the limit) are delivered - The `resumed` flag is set to `false` to indicate message gap +- Error is marked with `nonfatal: true` in the protocol + +The SDK automatically: +- Continues with partial message recovery +- Sets `stateChange.resumed = false` on channel attachment +- Provides error details in `stateChange.reason` for handling + +## SDK-Specific Behaviors + +### JavaScript/TypeScript SDKs +- Checks for `HistoryResponseType.Limit` in multiple recovery scenarios +- Handles timeline queries and regional ordering with this error +- Error includes `nonfatal: true` parameter + +### Ruby SDK +- May report byte sizes instead of message counts in error messages +- Example: "Channel message limit exceeded 86695 bytes" +- This appears to be a Ruby-specific implementation detail + +### SSE Clients +- Common with SSE clients that disconnect for extended periods +- Resume failures after `lastEventId` resume attempts +- Connection remains active despite resume failure + + ## Prevention - **Monitor disconnection duration**: Be aware that disconnections over 2 minutes may result in message gaps - **Use appropriate rewind values**: Keep rewind requests under 100 messages - **Implement fallback strategies**: Always have History API retrieval as backup -- **Consider message rates**: High-volume channels need special handling for recovery +- **Consider message rates**: High-volume channels (>20 messages/second) need special handling for recovery +- **Use time-limited rewind**: Combine time and count limits, e.g., `rewind=30s&rewindLimit=50` +- **Track connection state**: Monitor for `suspended` state to anticipate recovery issues ## Related Resources -- [Channel options and rewind limits](https://ably.com/docs/channels/options/rewind#limits) +- [Channel options and rewind limits](https://ably.com/docs/channels/options/rewind) - [History API documentation](https://ably.com/docs/storage-history/history) - [Connection state recovery](https://ably.com/docs/connect/states) -- Related error: [90003 - Messages Expired](./90003-messages-expired.md) +- [Channel parameters overview](https://ably.com/docs/realtime/channels/channel-parameters/overview) + +## Related Errors + +• **[90003 - Messages Expired](https://help.ably.io/error/90003)** + Similar error when messages have expired (>2 minutes old) rather than exceeding count limits + +• **[80002 - Connection Suspended](https://help.ably.io/error/80002)** + Connection enters suspended state after 2+ minutes disconnected, leading to recovery issues + +• **[80000 - Connection Failed](https://help.ably.io/error/80000)** + Complete connection failure that prevents any message recovery ## Need Further Help? @@ -130,6 +184,7 @@ When contacting support, please provide: - Steps to reproduce the issue - Any relevant code snippets (without sensitive credentials) - The SDK and version you're using +- Channel message rates and disconnection duration if known Our team will help you resolve this issue as quickly as possible. @@ -137,39 +192,47 @@ Our team will help you resolve this issue as quickly as possible. - + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/90005-channel-recovery-epoch-not-found.mdx b/src/pages/docs/platform/errors/codes/90005-channel-recovery-epoch-not-found.mdx index 130c881aee..6d42bfc248 100644 --- a/src/pages/docs/platform/errors/codes/90005-channel-recovery-epoch-not-found.mdx +++ b/src/pages/docs/platform/errors/codes/90005-channel-recovery-epoch-not-found.mdx @@ -1,20 +1,20 @@ - + - + # Error 90005: Channel Recovery Epoch Not Found ## What Happened -The channel couldn't recover its previous state because the requested recovery point no longer exists on Ably's servers. +The channel couldn't recover its previous state because the requested recovery point (epoch) no longer exists or doesn't match Ably's server records. ## Quick Reference @@ -25,8 +25,8 @@ The channel couldn't recover its previous state because the requested recovery p ## Quick Fix - Allow the SDK to handle this automatically - it will reattach without recovery -- Your channel will reconnect with fresh state -- No manual intervention required in most cases +- Your channel will continue working with fresh state +- If attaching to an empty channel, this may be a known issue that doesn't affect functionality ## Error Messages @@ -39,15 +39,19 @@ You may see this message: - Channel was disconnected for longer than the recovery window - Recovery data has expired on the server - Typically occurs after prolonged network outages + -2. **Channel with no message history** - - Attempting recovery on a channel that has never had messages - - Clean attachment to empty channels - +2. **Empty channel attachment** (known issue) + - Attempting to attach to a channel that has never had messages + - Clean attachment incorrectly triggers this error + - This is a known bug that doesn't affect channel functionality + 3. **Invalid recovery state** - Client has outdated or corrupted recovery information - - Recovery point never existed or was from different channel instance + - Recovery epoch never existed or was from a different channel instance + - Mismatch between client and server epoch records + ## Resolution Steps @@ -55,29 +59,30 @@ You may see this message: - Ably SDKs detect this error and automatically reattach without recovery - The channel continues working but without historical messages - No code changes needed in most cases - + -2. **If you need message history** - - Use the History API to retrieve missed messages after reattachment - - See [History documentation](https://ably.com/docs/storage-history/history) - +2. **For empty channels (if applicable)** + - If attaching to a new or empty channel, this error can be safely ignored + - The channel will function normally despite the error + - This is a known issue that may trigger unnecessary master queries + -3. **For critical message continuity** - - Implement client-side state tracking - - Use presence to detect when recovery fails - - Consider using persistent storage for critical data - +3. **If you need message history** + - Use the History API to retrieve missed messages after reattachment + - Implement client-side state tracking for critical data + - Consider using presence to detect when recovery fails + ## Automatic Handling Ably SDKs automatically handle this error by: -- Detecting the recovery failure +- Detecting the recovery failure (fatal error with `resultType === -1`) - Reattaching to the channel without recovery - Emitting an update event to notify your application - Continuing normal channel operation with fresh state The channel remains functional but loses continuity with previous messages. - + ## Prevention @@ -87,22 +92,37 @@ While this error is handled automatically, you can minimize its occurrence: - **Store critical state**: Keep important data client-side for reconstruction - **Use persistent history**: Enable extended history retention for critical channels - **Implement presence**: Use presence to detect and handle state loss +- **Be aware of empty channel behavior**: First attachment to empty channels may trigger this error harmlessly ## Performance Impact This error indicates: -- Loss of message continuity +- Loss of message continuity (except for empty channels) - Fresh channel state without history - Potential need to re-establish presence - No impact on future message delivery +- May cause unnecessary master RPC queries for empty channels + +## Related Errors + +• **[80008 - Connection Recovery Failed](https://help.ably.io/error/80008)** + Connection-level equivalent of this error - both represent "epoch not found" conditions + + +• **[90003 - Messages Expired](https://help.ably.io/error/90003)** + Recovery fails because messages have expired from the server + +• **[90004 - Message Limit Exceeded](https://help.ably.io/error/90004)** + Non-fatal recovery error allowing partial recovery, unlike 90005 + +• **[90006 - Unbounded Request](https://help.ably.io/error/90006)** + Recovery request was too broad or unbounded ## Related Resources -- [Channel state recovery](https://ably.com/docs/realtime/channels#state-recovery) -- [Connection state recovery](https://ably.com/docs/realtime/connection#connection-state-recovery) -- [History API](https://ably.com/docs/storage-history/history) -- [Presence documentation](https://ably.com/docs/presence) -- Related errors: [90003](./90003-messages-expired.md), [90004](./90004-message-limit-exceeded.md), [90006](./90006-unbounded-request.md) +- [Ably Documentation](https://ably.com/docs) +- [Support Portal](https://ably.com/support) +- Related errors in the 9000x recovery family ## Need Further Help? @@ -116,6 +136,7 @@ When contacting support, please provide: - Steps to reproduce the issue - Any relevant code snippets (without sensitive credentials) - The SDK and version you're using +- Whether this occurs on empty channels or channels with message history Our team will help you resolve this issue as quickly as possible. @@ -123,40 +144,49 @@ Our team will help you resolve this issue as quickly as possible. - + + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/90007-channel-operation-timeout.mdx b/src/pages/docs/platform/errors/codes/90007-channel-operation-timeout.mdx index 090af84d3b..281d7b1b28 100644 --- a/src/pages/docs/platform/errors/codes/90007-channel-operation-timeout.mdx +++ b/src/pages/docs/platform/errors/codes/90007-channel-operation-timeout.mdx @@ -1,13 +1,13 @@ - + - + # Error 90007: Channel operation timeout @@ -43,19 +43,19 @@ You may see one of these messages: - High latency or packet loss - Unstable network connection - Firewall or proxy interference - + 2. **Server response delays** (25% of cases) - Temporary server load - Regional connectivity issues - Network path problems - + 3. **Rapid operation sequences** (15% of cases) - Attempting attach/detach too quickly - Not waiting for previous operations to complete - - Session timeout handling issues - + - Session timeout handling issues (e.g., detaching during connection close) + ## Resolution steps @@ -63,13 +63,13 @@ You may see one of these messages: - The SDK automatically moves the channel to 'suspended' state and retries - No manual intervention required in most cases - Monitor the connection state if errors persist - + 2. **For detach timeout errors** - The channel remains in 'attached' state but reports the error - You can retry the detach operation after checking connection stability - Consider if detach is necessary - closing the connection handles channel cleanup automatically - + 3. **Increase timeout values if needed** ```javascript @@ -79,7 +79,7 @@ You may see one of these messages: channelRetryTimeout: 20000 // Increase retry timeout }); ``` - + 4. **Monitor channel state transitions** ```javascript @@ -87,17 +87,33 @@ You may see one of these messages: console.log('Channel suspended:', stateChange.reason); // SDK will automatically retry }); + + channel.on('attached', () => { + console.log('Channel successfully attached'); + }); + ``` + + +5. **Handle session timeout scenarios properly** + ```javascript + // DON'T do this - can cause race conditions + // await channel.detach(); + // await connection.close(); + + // DO this instead - connection close handles channel cleanup + await connection.close(); ``` - + ## Automatic handling Ably SDKs automatically handle this error: -- **For attach timeouts**: Channel moves to 'suspended' state and retries with exponential backoff -- **For detach timeouts**: Error is reported but channel remains functional +- **For attach timeouts**: Channel moves to 'suspended' state and retries with exponential backoff (RTL4f specification) +- **For detach timeouts**: Error is reported but channel remains functional, typically returning to 'attached' state - The SDK manages all retry logic - manual intervention is rarely needed +- Default timeout is 10 seconds (`Defaults.realtimeRequestTimeout`) - + ## Prevention @@ -105,14 +121,34 @@ Ably SDKs automatically handle this error: - Avoid rapid attach/detach cycles - Wait for operations to complete before initiating new ones - Use connection close instead of manual channel detach when ending sessions - +- Don't detach channels during connection close - it can cause race conditions + + +## Performance impact + +This error can affect your application in the following ways: +- **During attach timeout**: Channel operations are queued and delayed +- **During detach timeout**: Channel remains functional but may block subsequent detach attempts +- **State inconsistency**: Detach timeout can leave channel in an inconsistent state requiring reattachment + ## Related resources -- [Channel lifecycle documentation](https://ably.com/docs/channels#channel-lifecycle) -- [Connection state management](https://ably.com/docs/connect/states) -- [Timeout configuration options](https://ably.com/docs/connect#timeout-configuration) -- Related errors: [80002](https://help.ably.io/error/80002), [80000](https://help.ably.io/error/80000) +- [Channel lifecycle documentation](https://ably.com/docs/channels) +- [Connection state management](https://ably.com/docs/connect) +- [Timeout configuration options](https://ably.com/docs/connect) +- [RTL4f specification](https://sdk.ably.com/builds/ably/specification/main/features/#RTL4f) - Channel attach timeout behavior + +## Related errors + +• **[80002 - Connection suspended](https://help.ably.io/error/80002)** + Occurs when the connection is suspended after extended disconnection, similar timeout behavior + +• **[80000 - Connection failed](https://help.ably.io/error/80000)** + Connection-level failure that can cascade to channel operation timeouts + +• **[91000 - Unable to enter presence](https://help.ably.io/error/91000)** + Related channel operation that may timeout during attach operations ## Need further help? @@ -133,34 +169,45 @@ Our team will help you resolve this issue as quickly as possible. - + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/90010-channel-limit-exceeded.mdx b/src/pages/docs/platform/errors/codes/90010-channel-limit-exceeded.mdx index 14871ba1aa..1fbc67d0e7 100644 --- a/src/pages/docs/platform/errors/codes/90010-channel-limit-exceeded.mdx +++ b/src/pages/docs/platform/errors/codes/90010-channel-limit-exceeded.mdx @@ -1,13 +1,13 @@ - + - + # Error 90010: Channel limit exceeded @@ -25,43 +25,46 @@ You've exceeded the maximum number of channels allowed in a single request or co ## Quick fix - Split bulk operations into batches of 100 channels or fewer -- For connection limits, check your account's channel limit (typically 200-1000) +- For connection limits, verify your account's channel limit (standard: 200, enterprise: 1000+) - Implement pagination or batching for large channel operations +- Use multiple connections if you need more channels than your per-connection limit allows ## Error messages You may see one of these messages: - "Max number of channels permitted in a single bulk presence request (100) exceeded" - "Max number of channels permitted in a single bulk publish request (100) exceeded" -- "Maximum number of channels per connection 200 exceeded" (limit varies by account) +- "Maximum number of channels per connection 200 exceeded" (standard accounts) - "Maximum number of channels per connection 1000 exceeded" (enterprise accounts) +- "Maximum number of channels per connection 50 exceeded" (misconfigured accounts) ## Common causes -1. **Bulk operation exceeds 100 channels** (Most common for batch operations) - +1. **Bulk operation exceeds 100 channels** (70% of cases) + - Attempting bulk publish to more than 100 channels - Bulk presence request across more than 100 channels - Not implementing batching for large channel sets -2. **Per-connection limit exceeded** (Common for realtime connections) - +2. **Per-connection limit exceeded** (25% of cases) + - Standard accounts: exceeding 200 channels per connection - Enterprise accounts: exceeding configured limit (often 1000+) - Incorrectly configured accounts with 50 channel limit + - Food delivery platforms with high channel usage for order tracking -3. **Rapid channel attachment** (Less common) - +3. **Rapid channel attachment causing warnings** (5% of cases) + - Attaching to many channels quickly without checking limits + - Console spamming with warning messages every 10ms - Not reusing connections efficiently - - Creating new connections unnecessarily ## Resolution steps ### For bulk operations (100 channel limit) 1. **Split your batch requests** - + ```javascript // Split channels into batches of 100 const batchSize = 100; @@ -70,18 +73,22 @@ You may see one of these messages: batches.push(channels.slice(i, i + batchSize)); } - // Process each batch + // Process each batch sequentially for (const batch of batches) { - await client.request({ + await ably.request({ method: 'POST', path: '/messages', - body: batch + body: { + channels: batch, + messages: messageData + } }); } ``` - + 2. **Use parallel processing for better performance** + ```javascript // Process batches in parallel (be mindful of rate limits) const results = await Promise.all( @@ -92,28 +99,41 @@ You may see one of these messages: ### For per-connection limits 1. **Check your account's channel limit** - + - Standard accounts: 200 channels per connection - - Enterprise accounts: Can be configured higher (contact support for increases) - - Verify in your dashboard under account limits + - Enterprise accounts: Can be configured higher (1000+) + - Verify in your Ably dashboard under account limits + - For increases, upgrade to Enterprise or contact support 2. **Optimize channel usage** + + - Detach from channels when not actively in use - Use channel namespacing to reduce total channels - - Implement channel pooling for efficient reuse - - Consider using wildcards for subscriptions where appropriate + - Consider using transient publishes if you only need to send messages + - Use REST API for publish-only scenarios 3. **Distribute across multiple connections** + ```javascript - // Create multiple connections for large channel sets + // Calculate required connections + const channelLimit = 200; // Your account's limit const connectionsNeeded = Math.ceil(totalChannels / channelLimit); + + // Create multiple connections const connections = Array(connectionsNeeded).fill(null).map(() => new Ably.Realtime({ key: apiKey }) ); + + // Distribute channels across connections + channels.forEach((channel, index) => { + const connectionIndex = index % connectionsNeeded; + connections[connectionIndex].channels.get(channel); + }); ``` ## Automatic handling - + This error is not automatically retried by Ably SDKs. The entire batch is rejected without partial processing. Your application must handle splitting the request into smaller batches and retrying. ## Prevention @@ -121,13 +141,36 @@ This error is not automatically retried by Ably SDKs. The entire batch is reject - Implement a channel manager that tracks usage against limits - Use constants for batch sizes (max 100 for bulk operations) - Monitor channel usage in your application metrics -- For high-volume applications, contact Ably about enterprise limits +- For high-volume applications like food delivery or order tracking, request enterprise limits +- Implement connection pooling for efficient channel distribution +- Consider using wildcards for subscriptions where appropriate + +## Performance impact + + +This error can cause: +- Complete batch rejection without partial processing +- Console warning spam (potentially every 10ms) +- Connection instability if limits are repeatedly hit +- Increased latency from retry attempts + +## Related errors + +• **[40000 - Bad Request](https://help.ably.io/error/40000)** + General request errors that may occur alongside channel limit issues + +• **[80000 - Connection Failed](https://help.ably.io/error/80000)** + Connection failures that may result from excessive channel attachment attempts + +• **[91000 - Unable to Enter Presence](https://help.ably.io/error/91000)** + Presence operations that may fail when channel limits are exceeded ## Related resources -- [Channel limits documentation](https://faqs.ably.com/is-there-a-maximum-number-of-channels-per-connection) -- [Batch publishing guide](https://ably.com/docs/api/rest-api#batch-publish) -- [Connection limits](https://ably.com/docs/general/limits) +- [Channel limits FAQ](https://faqs.ably.com/is-there-a-maximum-number-of-channels-per-connection) +- [Batch operations documentation](https://ably.com/docs/api/rest-api#batch-publish) +- [Platform limits](https://ably.com/docs/general/limits) +- [Enterprise account features](https://ably.com/pricing/enterprise) ## Need further help? @@ -148,40 +191,51 @@ Our team will help you resolve this issue as quickly as possible. - + + + @@ -190,6 +244,6 @@ To improve this error code documentation: 1. First approach: Update editorial-notes.md in ably-os repository with specific guidance for error 90010 2. Regenerate: Run `./bin/ably-os errors document-error-codes 90010 --force` 3. For broader improvements: Review and update ably-os prompt templates -4. Context: See https://github.com/ably/ably-os/blob/main/docs/ERROR_COMMANDS_GUIDE.md +4. Context: See https://github.com/ably/ably-os/blob/5f4ba43/docs/ERROR_COMMANDS_GUIDE.md 5. Source repository: https://github.com/ably/ably-os --> \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/90099-generic-discontinuity.mdx b/src/pages/docs/platform/errors/codes/90099-generic-discontinuity.mdx index 2bfa90f137..703c68e7e3 100644 --- a/src/pages/docs/platform/errors/codes/90099-generic-discontinuity.mdx +++ b/src/pages/docs/platform/errors/codes/90099-generic-discontinuity.mdx @@ -1,11 +1,11 @@ - + @@ -36,30 +36,30 @@ You may see one of these messages: ## Common Causes 1. **Artificial discontinuity for testing** (Most common) - + - Administrative testing of discontinuity handling - Debug endpoint triggered discontinuity - Simulated message gap for validation 2. **Unspecified discontinuity scenario** - + - Generic fallback when specific discontinuity type unknown - Catch-all for unusual continuity breaks ## Resolution Steps 1. **Handle the discontinuity in your application** - + - Treat this as an indication that messages may have been missed - Your application should handle the potential gap in message continuity 2. **Retrieve missed messages if needed** - + - Use the [history API](https://ably.com/docs/storage-history/history) to fetch messages from before the discontinuity - Check the channel's continuity flag to confirm the break 3. **Refresh application state** - + - If your application maintains state based on messages, consider refreshing it - Re-sync any client-side state that depends on message ordering @@ -90,7 +90,17 @@ While discontinuities cannot always be prevented, you can minimize their impact: - [Message continuity documentation](https://ably.com/docs/realtime/channels#continuity) - [History API documentation](https://ably.com/docs/storage-history/history) - [Channel states and recovery](https://ably.com/docs/realtime/channels#states) -- Related errors: [90003](https://help.ably.io/error/90003) (Messages expired), [90004](https://help.ably.io/error/90004) (Message limit exceeded) + +## Related Errors + +• **[90003 - Messages Expired](https://help.ably.io/error/90003)** + Occurs when message retention period has been exceeded causing a continuity break + +• **[90004 - Message Limit Exceeded](https://help.ably.io/error/90004)** + Related discontinuity when the channel's message buffer limit is reached + +• **[90005 - No Matching Epoch](https://help.ably.io/error/90005)** + Discontinuity due to epoch mismatch preventing message recovery ## Need Further Help? @@ -111,10 +121,10 @@ Our team will help you resolve this issue as quickly as possible. - @@ -128,16 +138,19 @@ Our team will help you resolve this issue as quickly as possible. + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/91000-presence-requires-client-id.mdx b/src/pages/docs/platform/errors/codes/91000-presence-requires-client-id.mdx index c1e7a40bd3..a9b92ea965 100644 --- a/src/pages/docs/platform/errors/codes/91000-presence-requires-client-id.mdx +++ b/src/pages/docs/platform/errors/codes/91000-presence-requires-client-id.mdx @@ -1,13 +1,13 @@ - + - + # Error 91000: Presence requires client ID @@ -42,19 +42,19 @@ You may see one of these messages: - Using basic authentication without setting client ID - Missing client ID in token parameters - Quick-start implementations often miss this requirement - + 2. **Anonymous connection attempting presence** (8% of cases) - Default connections don't have client IDs - Demo applications without proper authentication setup - First-time developers not aware of clientId requirement - + 3. **Client ID lost during authentication renewal** (2% of cases) - Token renewal didn't include client ID - JWT token missing client ID claim - Cached token with outdated client ID - + ## Resolution Steps @@ -66,7 +66,7 @@ You may see one of these messages: clientId: 'unique-user-id' // Add this line }); ``` - + 2. **Configure client ID via token authentication** ```javascript @@ -86,7 +86,7 @@ You may see one of these messages: } }); ``` - + 3. **Use JWT with client ID claim** ```javascript @@ -102,7 +102,7 @@ You may see one of these messages: authMethod: 'GET' }); ``` - + 4. **Verify client ID is set before presence operations** ```javascript @@ -116,7 +116,7 @@ You may see one of these messages: console.error('Client ID required for presence operations'); } ``` - + ## Automatic Handling @@ -126,12 +126,12 @@ This is a client error that will not be automatically retried. You must configur Different SDKs validate client ID at different points: - **Go SDK**: Validates on Enter, Update, and Leave operations -- **Java SDK**: Validates in Auth.checkClientId() method -- **Ruby SDK**: Validates in enter_with_presence_message() +- **Java SDK**: Validates in Auth.checkClientId() method with HTTP 400 status +- **Ruby SDK**: Validates in enter_with_presence_message() with HTTP 400 status - **.NET SDK**: Uses error constant UnableToEnterPresenceChannelNoClientId All SDKs throw error 91000 consistently when client ID is missing. - + ## Prevention @@ -140,7 +140,7 @@ All SDKs throw error 91000 consistently when client ID is missing. - **Maintain consistency**: Use the same client ID across reconnections for the same user - **Validate before presence operations**: Check that client ID exists before calling presence methods - **Include in token renewal**: Ensure client ID persists through token refreshes - + ## Security Considerations @@ -149,15 +149,28 @@ All SDKs throw error 91000 consistently when client ID is missing. - **Avoid sensitive data**: Don't use personal information as client IDs - **Unique identifiers**: Ensure each user has a unique client ID to prevent conflicts - **Consistent assignment**: Server should control client ID assignment for security - + + +## Related Errors + +• **[91001 - Invalid Presence State](https://help.ably.io/error/91001)** + Occurs when attempting presence operations in an invalid channel state + +• **[91002 - Not Entered](https://help.ably.io/error/91002)** + Attempting to leave or update presence when not currently entered + +• **[91003 - Presence Member Limit](https://help.ably.io/error/91003)** + Maximum number of presence members exceeded on the channel + +• **[91004 - Auto Re-enter Failed](https://help.ably.io/error/91004)** + Automatic presence re-entry failed after connection recovery ## Related Resources -- [Ably Presence documentation](https://ably.com/docs/presence) +- [Ably Presence documentation](https://ably.com/docs/presence-occupancy/presence) - [Identified clients guide](https://ably.com/docs/auth/identified-clients) - [Token authentication](https://ably.com/docs/auth/token) -- [JWT authentication](https://ably.com/docs/auth/token#jwt) -- Related errors: [91001](./91001-invalid-presence-state.md), [91002](./91002-not-entered.md), [91003](./91003-presence-member-limit.md) +- [JWT authentication tutorial](https://ably.com/tutorials/jwt-authentication) ## Need Further Help? @@ -178,16 +191,15 @@ Our team will help you resolve this issue as quickly as possible. - + + + @@ -225,6 +240,6 @@ To improve this error code documentation: 1. First approach: Update editorial-notes.md in ably-os repository with specific guidance for error 91000 2. Regenerate: Run `./bin/ably-os errors document-error-codes 91000 --force` 3. For broader improvements: Review and update ably-os prompt templates -4. Context: See https://github.com/ably/ably-os/blob/main/docs/ERROR_COMMANDS_GUIDE.md +4. Context: See https://github.com/ably/ably-os/blob/5f4ba43/docs/ERROR_COMMANDS_GUIDE.md 5. Source repository: https://github.com/ably/ably-os --> \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/91001-presence-channel-invalid-state.mdx b/src/pages/docs/platform/errors/codes/91001-presence-channel-invalid-state.mdx index 2c06d0c6ec..b027c29002 100644 --- a/src/pages/docs/platform/errors/codes/91001-presence-channel-invalid-state.mdx +++ b/src/pages/docs/platform/errors/codes/91001-presence-channel-invalid-state.mdx @@ -1,13 +1,13 @@ - + - + # Error 91001: Presence operation failed due to invalid channel state @@ -42,25 +42,25 @@ You may see one of these messages: ## Common Causes 1. **Channel not attached** (60% of cases) - + - Attempting presence operations before attaching to channel - Channel has become detached due to network issues - Channel failed during connection problems 2. **Device wake/sleep cycles** (25% of cases) - + - Computer resumes after suspension (especially Windows) - Mobile app returns from background - Network transitions (WiFi to cellular) 3. **Race conditions** (10% of cases) - + - Channel state changes during presence operation - Multiple simultaneous operations on same channel - Timing issues during connection recovery 4. **Long-running connections** (5% of cases) - + - Extended disconnection causing channel suspension - Connection state not properly managed - Missing error recovery logic @@ -79,7 +79,7 @@ You may see one of these messages: }); } ``` - + 2. **Attach to the channel first** ```javascript @@ -87,7 +87,7 @@ You may see one of these messages: await channel.attach(); await channel.presence.enter({ name: 'User Name' }); ``` - + 3. **Handle channel state transitions** ```javascript @@ -102,8 +102,13 @@ You may see one of these messages: // Re-enter presence if needed channel.presence.enter(); }); + + channel.on('failed', () => { + console.log('Channel failed - requires new connection'); + // Handle terminal failure state + }); ``` - + 4. **Implement recovery for device wake scenarios** ```javascript @@ -121,7 +126,31 @@ You may see one of these messages: } }); ``` - + + +5. **Implement robust retry logic** + ```javascript + async function enterPresenceWithRetry(maxAttempts = 3) { + for (let attempt = 1; attempt <= maxAttempts; attempt++) { + try { + // Ensure channel is attached + if (channel.state !== 'attached') { + await channel.attach(); + } + await channel.presence.enter(); + return; // Success + } catch (error) { + if (error.code === 91001 && attempt < maxAttempts) { + // Wait before retry (exponential backoff not needed) + await new Promise(resolve => setTimeout(resolve, 1000 * attempt)); + } else { + throw error; // Give up after max attempts + } + } + } + } + ``` + ## Automatic Handling @@ -131,7 +160,7 @@ Ably SDKs do not automatically retry presence operations when this error occurs. - Retry presence operations after successful attachment Some SDKs queue presence operations during the `attaching` state, but will fail if the channel is `detached`, `failed`, or `suspended`. - + ## Prevention @@ -140,7 +169,8 @@ Some SDKs queue presence operations during the `attaching` state, but will fail - Handle device sleep/wake events appropriately - Use channel state event listeners to maintain presence - Consider implementing automatic re-entry logic after reconnection - +- For long-running applications, implement periodic connection health checks + ## Channel States Reference @@ -149,21 +179,51 @@ Presence operations are only allowed in the `attached` state: | State | Presence Allowed | Description | |-------|------------------|-------------| | `initialized` | No | Channel created but not connected | -| `attaching` | Queued | Operations queued until attached | +| `attaching` | Queued* | Operations queued until attached | | `attached` | ✅ Yes | Only state allowing presence | | `detaching` | No | Channel being removed | | `detached` | No | Not connected to channel | | `failed` | No | Channel in error state | -| `suspended` | No | Channel temporarily unavailable | +| `suspended` | No | Channel temporarily unavailable (after 2+ minutes disconnected) | + +*Some SDKs queue operations during `attaching`, others reject immediately + + +## Platform-Specific Considerations - +### Windows +Windows computers are particularly susceptible to this error after resuming from sleep mode. The channel often enters a detached state during suspension and requires explicit reattachment. + +### Mobile (iOS/Android) +Mobile apps transitioning between background and foreground states may encounter this error. Implement lifecycle handlers to manage presence state appropriately. + +### Asset Tracking SDK +The Asset Tracking SDK treats error 91001 as non-fatal and automatically retries after 15 seconds when encountering "Enter presence on suspended channel". + ## Related Resources - [Presence documentation](https://ably.com/docs/presence) - [Channel state lifecycle](https://ably.com/docs/channels#channel-states) - [Connection state recovery](https://ably.com/docs/connect/states) -- Related errors: [91000](https://help.ably.io/error/91000), [91004](https://help.ably.io/error/91004), [91005](https://help.ably.io/error/91005) +- [Handling connection failures](https://ably.com/docs/connect/failures) + +## Related Errors + +• **[91000 - No Client ID Configured](https://help.ably.io/error/91000)** + Presence operations require a client ID to be set during authentication + +• **[91004 - Auto Re-enter Failed](https://help.ably.io/error/91004)** + Automatic presence re-entry failed after connection recovery + +• **[91005 - Presence State Out of Sync](https://help.ably.io/error/91005)** + Presence set has become inconsistent and requires resynchronization + +• **[80002 - Channel Suspended](https://help.ably.io/error/80002)** + Channel enters suspended state after extended disconnection, preventing all operations + +• **[80000 - Connection Failed](https://help.ably.io/error/80000)** + Connection failure that may cause channels to detach ## Need Further Help? @@ -184,40 +244,47 @@ Our team will help you resolve this issue as quickly as possible. - + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/91004-presence-auto-reenter-failed.mdx b/src/pages/docs/platform/errors/codes/91004-presence-auto-reenter-failed.mdx index 9dd2fcaf9c..ceeef8b9f8 100644 --- a/src/pages/docs/platform/errors/codes/91004-presence-auto-reenter-failed.mdx +++ b/src/pages/docs/platform/errors/codes/91004-presence-auto-reenter-failed.mdx @@ -1,13 +1,13 @@ - + - + # Error 91004: Presence auto-reenter failed @@ -42,21 +42,25 @@ You may see one of these messages: - Token expired while disconnected - Permissions changed during downtime - Capability no longer includes presence rights + 2. **Channel state incompatibility** (30% of cases) - Channel suspended after extended disconnection - Presence member limit reached - Channel closed and reopened with different parameters + 3. **Extended disconnection** (20% of cases) - Connection recovery took too long - Presence TTL expired - Server cleared presence state + 4. **Permission changes** (10% of cases) - Channel access revoked - Presence capability removed - Account or app suspended + ## Resolution Steps @@ -76,7 +80,7 @@ You may see one of these messages: } }); ``` - + 2. **Check and refresh authentication if needed** ```javascript @@ -105,11 +109,20 @@ You may see one of these messages: } catch (err) { console.error('Presence recovery failed:', err); - // Notify your application that presence is unavailable + + // Check the underlying error code for specific issues + if (err.cause?.code === 40160) { + // Capability issue - need to refresh auth with proper permissions + await ably.auth.authorize(); + await channel.presence.enter(); + } else { + // Notify your application that presence is unavailable + notifyPresenceFailure(err); + } } } ``` - + 4. **Monitor connection state for proactive handling** ```javascript @@ -131,15 +144,16 @@ You may see one of these messages: ## Automatic Handling -When a connection recovers after disconnection, Ably SDKs automatically attempt to re-enter presence for all channels where the client was previously present. Error 91004 indicates this automatic process failed. The SDK will: +When a connection recovers after disconnection, Ably SDKs automatically attempt to re-enter presence for all channels where the client was previously present (RTP17i specification). Error 91004 indicates this automatic process failed. The SDK will: - Emit an 'update' event on the channel with this error - Set the `resumed` flag to `true` in the state change +- Include the original error in the `cause` field (useful for identifying specific permission issues) - Log the error at warning level or higher - Continue normal channel operation (only presence is affected) The channel remains functional for publishing and subscribing to messages; only the presence state needs manual recovery. - + ## Prevention @@ -147,13 +161,29 @@ The channel remains functional for publishing and subscribing to messages; only - **Handle presence errors proactively**: Listen for 'update' events with error codes to detect issues early - **Store presence data locally**: Keep a local copy of presence data to facilitate recovery - **Monitor connection stability**: Track disconnection patterns and implement appropriate recovery strategies +- **Use connection state callbacks**: Implement handlers for connection state changes to manage presence proactively +- **Check underlying error causes**: Examine the `cause` field in the error for specific issues like capability problems (40160) + +## Related Errors + +• **[91000 - No ClientId for Presence](https://help.ably.io/error/91000)** + Occurs when attempting presence operations without a configured client ID + +• **[91001 - Invalid Channel State](https://help.ably.io/error/91001)** + Channel is in a state that doesn't allow presence operations + +• **[91005 - Presence State Out of Sync](https://help.ably.io/error/91005)** + Presence state has become inconsistent and requires resynchronization + +• **[40160 - Capability Not Permitted](https://help.ably.io/error/40160)** + Operation not permitted with provided capability - often the underlying cause of 91004 ## Related Resources -- [Presence documentation](https://ably.com/docs/presence) -- [Connection state management](https://ably.com/docs/realtime/connection) -- [Authentication best practices](https://ably.com/docs/auth/token) -- Related errors: [91000](./91000-no-clientid-for-presence.mdx), [91001](./91001-invalid-channel-state.mdx) +- [Presence documentation](https://ably.com/docs) +- [Connection state management](https://ably.com/docs) +- [Authentication best practices](https://ably.com/docs) +- [Presence feature specification](https://sdk.ably.com/builds/ably/specification/main/features/#RTP17) ## Need Further Help? @@ -174,11 +204,11 @@ Our team will help you resolve this issue as quickly as possible. - @@ -189,23 +219,28 @@ Our team will help you resolve this issue as quickly as possible. - Manual re-entry pattern from knowledge file lines 33-44 - Comprehensive recovery from knowledge file lines 162-176 - Connection monitoring adapted from Ably docs -- Code Examples Rationale: Included essential recovery patterns verified against SDK implementations + - Slack discussion insights from lines 89-107 and 111-121 +- Code Examples Rationale: Included essential recovery patterns verified against SDK implementations in analysis file --> + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/91005-presence-state-out-of-sync.mdx b/src/pages/docs/platform/errors/codes/91005-presence-state-out-of-sync.mdx index 279e530874..4653917106 100644 --- a/src/pages/docs/platform/errors/codes/91005-presence-state-out-of-sync.mdx +++ b/src/pages/docs/platform/errors/codes/91005-presence-state-out-of-sync.mdx @@ -1,13 +1,13 @@ - + - + --- @@ -20,7 +20,7 @@ description: "The presence state for this channel has become desynchronized and ## What Happened -The presence state for this channel has lost synchronization with the server, meaning the list of members currently in the channel may be inaccurate or incomplete. +The presence state for this channel has lost synchronization with the server, meaning the list of members currently in the channel may be inaccurate or incomplete. This typically occurs when a channel enters the SUSPENDED state or when the connection is interrupted during presence synchronization. ## Quick Reference @@ -45,22 +45,22 @@ You may see one of these messages: ## Common Causes 1. **Channel suspension** (70% of cases) - - Channel entered SUSPENDED state during presence synchronization - - Typically occurs after 2+ minutes of disconnection - - Presence sync cannot complete while suspended - + - Channel entered SUSPENDED state after 2+ minutes of disconnection + - Presence sync cannot complete while channel is suspended + - Automatic recovery occurs when connection is restored + 2. **Connection interruption during sync** (20% of cases) - - Network disconnection while presence was synchronizing - - Sync process interrupted before completion - - Partial presence data received - + - Network disconnection occurred while presence was synchronizing + - Sync process was interrupted before completion + - Partial presence data may have been received + 3. **Synchronization timeout** (10% of cases) - - Server took too long to send presence data + - Server took too long to send complete presence data - High presence member count causing delays - - Network latency issues - + - Network latency preventing timely sync completion + ## Resolution Steps @@ -68,14 +68,18 @@ You may see one of these messages: - Ably SDKs automatically resynchronize presence when the channel reattaches - Monitor the channel state for recovery: ```javascript - channel.on('attached', () => { + channel.on('attached', (stateChange) => { console.log('Channel reattached, presence will resynchronize'); + // The resumed flag indicates if message continuity was preserved + if (!stateChange.resumed) { + console.log('Presence state was reset - full resync occurred'); + } }); ``` - + 2. **Check synchronization status** - - Verify presence is synchronized before using the data: + - Always verify presence is synchronized before using the data: ```javascript if (channel.presence.syncComplete) { // Safe to use presence data @@ -84,10 +88,11 @@ You may see one of these messages: // Wait for sync to complete channel.presence.once('sync', async () => { const members = await channel.presence.get(); + console.log('Presence synchronized with', members.length, 'members'); }); } ``` - + 3. **Force resynchronization if needed** - For immediate recovery, manually detach and reattach: @@ -100,29 +105,35 @@ You may see one of these messages: // Wait for sync completion channel.presence.once('sync', () => { - console.log('Presence resynchronized'); + console.log('Presence resynchronized successfully'); }); ``` - + -4. **Monitor channel state** - - Implement proper state handling: +4. **Monitor channel state transitions** + - Implement proper state handling to anticipate sync issues: ```javascript channel.on('suspended', () => { console.log('Channel suspended - presence may be out of sync'); + // Update UI to indicate presence data may be stale }); - channel.on('attached', () => { - console.log('Channel attached - presence synchronizing'); + channel.on('attached', (stateChange) => { + if (stateChange.resumed) { + console.log('Channel attached with continuity preserved'); + } else { + console.log('Channel attached - full presence resync required'); + } }); ``` - + ## Automatic Handling Ably SDKs automatically handle presence resynchronization: - When a channel moves from SUSPENDED to ATTACHED state, presence sync is automatically initiated - The SDK discards the old presence state and fetches a fresh copy from the server +- The `syncComplete` flag is set to `false` during sync and `true` when complete - No manual intervention required for standard recovery scenarios ## Prevention @@ -131,14 +142,25 @@ Ably SDKs automatically handle presence resynchronization: - **Use the syncComplete flag**: Always check synchronization status before relying on presence data - **Handle suspended state**: Implement appropriate UI feedback when channels are suspended - **Consider caching**: Store last known good presence state for reference during sync issues - +- **Monitor presence events**: Subscribe to presence events to maintain local state awareness + ## Related Resources -- [Presence documentation](https://ably.com/docs/presence) -- [Connection state management](https://ably.com/docs/realtime/connection) -- [Channel states explained](https://ably.com/docs/realtime/channels#states) -- Related errors: [91001 - Invalid channel state](./91001-invalid-channel-state.mdx), [91004 - Auto re-enter failed](./91004-auto-reenter-failed.mdx) +- [Presence documentation](https://ably.com/docs/presence-occupancy/presence) +- [Connection state and recovery](https://ably.com/docs/connect/states) +- [Channel states explained](https://ably.com/docs/channels/states) + +## Related Errors + +• **[91001 - Invalid channel state](https://help.ably.io/error/91001)** + Channel operation attempted in an invalid state, preventing presence operations + +• **[91004 - Auto re-enter failed](https://help.ably.io/error/91004)** + Automatic presence re-entry failed after reconnection, requiring manual intervention + +• **[91100 - Member implicitly left](https://help.ably.io/error/91100)** + Presence member was removed due to timeout or disconnection ## Need Further Help? @@ -159,36 +181,44 @@ Our team will help you resolve this issue as quickly as possible. - + + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/91100-member-implicitly-left-presence.mdx b/src/pages/docs/platform/errors/codes/91100-member-implicitly-left-presence.mdx index e6d462dc5d..1d6a1455c9 100644 --- a/src/pages/docs/platform/errors/codes/91100-member-implicitly-left-presence.mdx +++ b/src/pages/docs/platform/errors/codes/91100-member-implicitly-left-presence.mdx @@ -1,69 +1,76 @@ - + - + # Error 91100: Member implicitly left presence channel ## What Happened -A presence member was automatically removed from a channel when their connection ended unexpectedly or the system detected an inconsistent state. +A presence member was automatically removed from a channel when their connection ended unexpectedly, the system detected an inconsistent state, or server topology changes occurred. ## Quick Reference | Error Code | HTTP Status | Category | Retryable | |------------|-------------|----------|-----------| -| 91100 | 400 | Presence/Channel (Realtime) | No - indicates automatic cleanup | +| 91100 | 400 | Presence/Channel (Realtime) | No - indicates automatic cleanup already completed | ## Quick Fix - This is an informational error indicating automatic presence cleanup - No action required - the system has already removed the member - Update your UI to reflect the member's departure +- Monitor frequency if occurring regularly ## Error Messages -You may see one of these messages in presence leave events: -- "Member implicitly left presence channel (connection closed)" -- "Member implicitly left presence channel (no owners)" -- "Member implicitly left presence channel (every owning instance removed)" -- "Member implicitly left presence channel (unexpected owning instance)" +You may see one of these message variations in presence leave events: +- "Member implicitly left presence channel (connection closed)" - Most common, connection terminated +- "Member implicitly left presence channel (no owners)" - Presence member has no owning server instances +- "Member implicitly left presence channel (every owning instance removed)" - All servers managing this member are gone +- "Member implicitly left presence channel (unexpected owning instance)" - Server role mismatch detected + ## Common Causes -1. **Unexpected disconnection** (80% of cases) - - Client lost network connection - - Application crashed or was terminated - - Browser tab or mobile app was closed - - Network timeout or failure - - -2. **Server maintenance or topology changes** (15% of cases) - - Frontend server deployment or restart - - Server instance migration +1. **Unexpected disconnection** (70% of cases) + - Client lost network connectivity + - Application crashed or was forcefully terminated + - Browser tab or mobile app was closed without cleanup + - Network timeout or WebSocket connection dropped (code 1006) + - Device went to sleep or lost power + + +2. **Server topology changes** (20% of cases) + - Frontend server deployment or rolling restart + - Server instance migration or failover - Regional failover events - + - Load balancer topology updates + - Planned maintenance activities + -3. **Validation failures** (5% of cases) - - Presence set inconsistency detected - - Ownership validation failed +3. **Validation and consistency checks** (10% of cases) + - Presence set inconsistency detected during periodic validation + - Ownership validation failed (orphaned members) - Cross-region synchronization issues - + - Members leaked between regions during connection migration + ## Resolution Steps 1. **Understand this is automatic cleanup** - - Ably has already removed the member from presence - - No manual intervention needed - - The system is working as designed - + - Ably has already removed the member from the presence set + - No manual intervention is needed or possible + - The system is working as designed to maintain consistency + - This distinguishes ungraceful disconnections from explicit leaves + 2. **Handle in your presence subscriber** ```javascript @@ -71,30 +78,93 @@ You may see one of these messages in presence leave events: if (member.reason?.code === 91100) { // Member left unexpectedly (connection lost, crash, etc.) console.log(`${member.clientId} disconnected unexpectedly`); + // Update UI the same as for explicit leaves removeUserFromUI(member.clientId); + + // Optional: Track for monitoring/analytics + trackImplicitLeave(member.clientId, member.reason.message); } }); ``` - + -3. **For debugging unexpected leaves** - - Check client-side connection stability - - Monitor for patterns of implicit leaves - - Review application lifecycle handling +3. **For debugging frequent implicit leaves** + - Check client-side connection stability and network quality + - Monitor for patterns (specific times, regions, or users) + - Review application lifecycle handling (especially mobile) - Ensure proper cleanup on app termination - + - Check for WebSocket connection issues (firewall, proxy) + - Review server deployment schedules if correlated with timing + + +4. **Monitor as a health indicator** + - High frequency of 91100 errors may indicate: + - Network infrastructure issues + - Client application stability problems + - Aggressive device power management + - Server deployment or topology issues + ## Automatic Handling Ably automatically: -- Detects when presence members lose connection -- Removes them from the presence set after timeout -- Broadcasts leave events with error code 91100 -- Maintains presence set consistency across regions - -No retry is needed or possible - the member has already been removed. - +- Detects when presence members lose connection unexpectedly +- Removes them from the presence set after connection timeout +- Broadcasts leave events with error code 91100 to all subscribers +- Maintains presence set consistency across all regions +- Handles server topology changes transparently +- Performs periodic validation to detect and clean up orphaned members + +No retry is needed or possible - the member has already been removed from presence. + + +## Code Examples + +### Comprehensive Presence Handling +```javascript +// Initialize presence with proper error handling +const channel = ably.channels.get('chat-room'); + +// Enter presence with data +await channel.presence.enter({ + name: 'John Doe', + status: 'online' +}); + +// Subscribe to all presence events +channel.presence.subscribe((presenceMsg) => { + switch (presenceMsg.action) { + case 'enter': + addUserToUI(presenceMsg.clientId, presenceMsg.data); + break; + + case 'leave': + // Handle both explicit and implicit leaves + if (presenceMsg.reason?.code === 91100) { + console.log(`Implicit leave: ${presenceMsg.clientId}`); + // Log the specific reason for debugging + console.log(`Reason: ${presenceMsg.reason.message}`); + } + removeUserFromUI(presenceMsg.clientId); + break; + + case 'update': + updateUserInUI(presenceMsg.clientId, presenceMsg.data); + break; + } +}); + +// Implement graceful shutdown to prevent implicit leaves +window.addEventListener('beforeunload', async () => { + try { + await channel.presence.leave(); + } catch (e) { + // Best effort - connection may already be closed + } +}); +``` + ## Prevention @@ -102,29 +172,64 @@ To minimize implicit leaves: 1. **Implement graceful shutdown** ```javascript - // Clean leave on app termination + // Browser/web applications window.addEventListener('beforeunload', async () => { await channel.presence.leave(); }); + + // Node.js applications + process.on('SIGTERM', async () => { + await channel.presence.leave(); + process.exit(0); + }); + + // Mobile applications - handle app lifecycle + // (iOS/Android specific handlers needed) ``` - + 2. **Handle connection lifecycle properly** - - Monitor connection state changes - - Implement reconnection logic where appropriate + - Monitor connection state changes for early detection + - Implement appropriate reconnection logic - Use presence heartbeats for critical applications + - Consider connection state recovery features + 3. **Design for implicit leaves** - Treat implicit and explicit leaves identically in UI - Don't show error messages to users for implicit leaves - Consider it normal behavior in distributed systems + - Implement "last seen" timestamps as a fallback + + +## Performance Impact + +This error has minimal performance impact: +- Cleanup happens automatically server-side +- No additional network requests required +- Presence set remains consistent +- Other channel operations continue normally +- Does not affect message publishing or subscriptions ## Related Resources -- [Presence documentation](https://ably.com/docs/presence) -- [Connection state management](https://ably.com/docs/realtime/connection) -- [Presence best practices](https://ably.com/docs/best-practice#presence) -- Related errors: [91000](https://help.ably.io/error/91000), [91001](https://help.ably.io/error/91001), [91004](https://help.ably.io/error/91004), [91005](https://help.ably.io/error/91005) +- [Presence documentation](https://ably.com/docs/presence-occupancy/presence) +- [Connection state and recovery](https://ably.com/docs/connect/states) +- [Connection state recovery FAQ](https://faqs.ably.com/connection-state-recovery) + +## Related Errors + +• **[91000 - Unable to enter presence without clientId](https://help.ably.io/error/91000)** + Occurs when attempting presence operations without proper client identification + +• **[91001 - Invalid channel state for presence](https://help.ably.io/error/91001)** + Related to channel state issues that may trigger implicit leaves + +• **[91004 - Presence auto re-enter failed](https://help.ably.io/error/91004)** + Automatic presence recovery failed after connection restoration + +• **[91005 - Presence set out of sync](https://help.ably.io/error/91005)** + Presence synchronization issues that may lead to cleanup operations ## Need Further Help? @@ -135,9 +240,11 @@ If you're still experiencing issues after trying these steps, our support team i When contacting support, please provide: - Your account ID and app ID - The full error message including error code 91100 +- Frequency and pattern of implicit leaves - Steps to reproduce the issue - Any relevant code snippets (without sensitive credentials) - The SDK and version you're using +- Connection logs if available Our team will help you resolve this issue as quickly as possible. @@ -146,29 +253,44 @@ Our team will help you resolve this issue as quickly as possible. + + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/92000-liveobjects-validation-error.mdx b/src/pages/docs/platform/errors/codes/92000-liveobjects-validation-error.mdx index b9bc359c4b..f378c5be49 100644 --- a/src/pages/docs/platform/errors/codes/92000-liveobjects-validation-error.mdx +++ b/src/pages/docs/platform/errors/codes/92000-liveobjects-validation-error.mdx @@ -1,20 +1,20 @@ - + - + # Error 92000: LiveObjects validation error ## What Happened -A LiveObjects operation failed validation due to invalid data, missing state, or synchronization issues. +A LiveObjects operation failed validation due to invalid data, missing state, or synchronization issues in Ably's distributed data structures. ## Quick Reference @@ -24,91 +24,156 @@ A LiveObjects operation failed validation due to invalid data, missing state, or ## Quick Fix -- Validate object IDs before operations -- Ensure objects exist before updates -- Handle state synchronization errors -- Consider resynchronizing LiveObjects state +- Validate object IDs match expected format before operations +- Ensure LiveObjects are synchronized before attempting updates +- Implement proper error recovery with state resynchronization +- Check for race conditions in concurrent operations ## Error Messages -You may see one of these messages: -- "Invalid serial: {serial}" -- "Invalid site code: {siteCode}" -- "Missing object state; LiveCounter objectId={id}" -- "Missing object state; LiveMap objectId={id}" -- "Invalid object id string" +You may encounter one of these variations: +- "Invalid serial: {serial}" - Operation serial number is invalid +- "Invalid site code: {siteCode}" - Site identifier validation failed +- "Missing object state; LiveCounter objectId={id}" - LiveCounter state not found +- "Missing object state; LiveMap objectId={id}" - LiveMap state not found +- "Invalid object id string" - Object ID format is incorrect ## Common Causes -1. **Invalid Object ID** (40% of cases) - +1. **Invalid Object ID Format** (40% of cases) + - Malformed object ID string - - Invalid format or characters - - Attempting to parse corrupted ID + - Invalid characters in ID + - Attempting to parse corrupted or truncated IDs + - Using client-generated IDs that don't match system format 2. **Missing Object State** (30% of cases) - - - Object not yet synchronized - - State lost during disconnection - - Attempting operations on non-existent objects + + - Object not yet synchronized after connection + - State lost during network disconnection + - Operations on objects that haven't been created + - Race condition where object deleted before operation 3. **Invalid Operation Sequencing** (20% of cases) - - - Invalid serial number in operation - - Invalid site code - - Out-of-order operations - -4. **Synchronization Issues** (10% of cases) - + + - Serial numbers out of sequence + - Invalid or unrecognized site code + - Operations arriving out of order + - Conflicting concurrent operations + +4. **Network and Synchronization Issues** (10% of cases) + - Network partitions causing state divergence - - Race conditions between concurrent operations - - State corruption during synchronization + - Timing-dependent race conditions + - State corruption during sync + - Incomplete initial synchronization ## Resolution Steps -1. **Validate object IDs before operations** - - - Check ID format is valid - - Ensure ID exists in your system - - Verify ID hasn't been corrupted - -2. **Check object existence** - - - Verify the LiveObject exists before operations - - Wait for initial synchronization to complete - - Handle missing state gracefully - -3. **Implement error recovery** - - - Detect 92000 errors in catch blocks - - Clear local LiveObjects state - - Fetch fresh state from server - - Retry the operation after resynchronization - -4. **Monitor operation ordering** - +1. **Validate Object IDs Before Operations** + + - Check ID format matches expected pattern + - Ensure ID hasn't been truncated or corrupted + - Verify ID exists in your application's context + - Use try-catch blocks around ID parsing operations + +2. **Ensure Object Existence and Synchronization** + + - Wait for initial LiveObjects synchronization to complete + - Verify the object exists before performing updates + - Check connection state before operations + - Handle missing state errors gracefully + +3. **Implement Comprehensive Error Recovery** + + ```javascript + try { + await liveObject.update(operation); + } catch (err) { + if (err.code === 92000) { + // Clear local state + await clearLocalState(); + // Fetch fresh state from server + await resynchronize(); + // Retry operation + await liveObject.update(operation); + } + } + ``` + + +4. **Handle Operation Ordering Issues** + - Ensure operations have valid serial numbers - - Check site codes are correct - - Handle concurrent operations properly + - Verify site codes match expected values + - Implement idempotent operations where possible + - Use proper concurrency controls ## Automatic Handling -This error indicates a validation failure that cannot be automatically resolved. Your application must handle the error by fixing the validation issue or resynchronizing state. +LiveObjects validation errors require manual intervention. The SDK cannot automatically resolve these issues as they indicate: +- Data integrity problems that need correction +- State synchronization issues requiring resync +- Invalid operations that must be fixed at the source + +## Code Examples + +### Proper Error Handling Pattern +```javascript +// Validate before operations +function isValidObjectId(id) { + // Check format based on your ID pattern + return id && typeof id === 'string' && id.length > 0; +} + +// Handle validation errors +async function updateLiveObject(liveObject, operation) { + if (!isValidObjectId(liveObject.id)) { + throw new Error('Invalid object ID format'); + } + + try { + await liveObject.update(operation); + } catch (error) { + if (error.code === 92000) { + console.error('LiveObjects validation error:', error.message); + // Implement recovery strategy + await recoverFromValidationError(liveObject); + } + throw error; + } +} +``` + ## Prevention -- **Validate inputs**: Always validate object IDs and data before operations - -- **Handle disconnections**: Implement proper state recovery after connection loss -- **Use idempotent operations**: Design operations to be safely retryable -- **Monitor errors**: Track validation errors to identify patterns +- **Input Validation**: Always validate object IDs and operation data before submission + +- **State Recovery**: Implement robust state recovery after connection loss + +- **Idempotent Design**: Make operations safely retryable + +- **Error Monitoring**: Track validation errors to identify patterns + +- **Synchronization Checks**: Verify sync completion before operations + ## Related Resources -- [LiveObjects documentation](https://ably.com/docs/products/liveobjects) -- [Ably LiveObjects Product Page](https://ably.com/liveobjects) -- [Connection state management](https://ably.com/docs/realtime/connection) -- Related errors: Other 92xxx error codes for LiveObjects-specific issues +- [Ably LiveObjects](https://ably.com/liveobjects) - Product overview and capabilities +- [Ably Support](https://ably.com/support) - Get help from our team + +## Related Errors + +• **[92001 - LiveObjects Operation Failed](https://help.ably.io/error/92001)** + General LiveObjects operation failures beyond validation issues + +• **[92002 - LiveObjects Sync Error](https://help.ably.io/error/92002)** + Synchronization failures between LiveObjects instances + +• **[92003 - LiveObjects Conflict](https://help.ably.io/error/92003)** + Concurrent operation conflicts requiring resolution ## Need Further Help? @@ -129,11 +194,11 @@ Our team will help you resolve this issue as quickly as possible. - @@ -142,30 +207,33 @@ Our team will help you resolve this issue as quickly as possible. - Content Excluded: None - all relevant information included - Recommendations Source: - Validation approach from knowledge file lines 57-63 - - Error recovery strategy from knowledge file lines 77-82 + - Error recovery strategy from knowledge file lines 65-82 - Prevention practices from knowledge file lines 84-89 -- Code Examples Rationale: No code examples included as they would require specific LiveObjects API knowledge not available in research +- Code Examples Rationale: Included essential error handling pattern from knowledge file to demonstrate proper recovery approach --> + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/92001-conflicting-usage.mdx b/src/pages/docs/platform/errors/codes/92001-conflicting-usage.mdx index f0fd63bf17..2b5080e792 100644 --- a/src/pages/docs/platform/errors/codes/92001-conflicting-usage.mdx +++ b/src/pages/docs/platform/errors/codes/92001-conflicting-usage.mdx @@ -1,11 +1,11 @@ - + @@ -24,7 +24,6 @@ This error code has two different meanings depending on which Ably feature you'r ## Quick Fix -Determine which scenario applies to you: - **Using Ruby SDK with encrypted channels?** Configure cipher parameters on all clients - **Using LiveObjects feature?** Reduce objects on channel or upgrade your package limits - **Unsure?** Check the full error message for context clues @@ -53,13 +52,27 @@ You may see one of these messages: - Some clients encrypted, others not - Updated encryption without updating all clients +3. **New client joining encrypted channel** (5% of Ruby SDK cases) + - Existing channel uses encryption + - New client code missing cipher configuration + - Attempting to subscribe without decryption setup + + + ### Scenario 2: LiveObjects Limit Exceeded 1. **Too many objects on channel** - - Exceeded account or application limits - - Objects not being cleaned up properly + - Default limit of 100 objects per channel + - Objects persist for 90 days - Accumulation of unused objects +2. **Insufficient cleanup** + - Objects not being removed after use + - Missing cleanup logic in application + - Long-running channels accumulating objects + + + ## Resolution Steps ### For Ruby SDK Channel Encryption Issues @@ -71,7 +84,7 @@ You may see one of these messages: cipher_params = Ably::Util::Crypto.get_default_params(key: cipher_key) channel = client.channels.get('channel-name', cipher: cipher_params) ``` - + 2. **Ensure all clients use identical configuration** ```ruby @@ -79,31 +92,57 @@ You may see one of these messages: shared_cipher_key = 'your-256-bit-key' # Must be identical across all clients cipher_params = Ably::Util::Crypto.get_default_params(key: shared_cipher_key) - # Apply to channel + # Apply to channel on both publishers and subscribers encrypted_channel = ably.channels.get('secure-channel', cipher: cipher_params) ``` - + 3. **Verify encryption is applied consistently** - Check all publisher clients have encryption configured - Ensure all subscriber clients have matching configuration - Review any recent changes to encryption setup + - Verify cipher key is the same across all environments + +4. **Handle encrypted messages gracefully** + ```ruby + begin + channel.subscribe do |message| + # Process decrypted message + puts message.data + end + rescue Ably::Exceptions::CipherError => e + if e.code == 92001 + puts "Channel requires encryption configuration" + # Configure cipher and retry + end + end + ``` + ### For LiveObjects Limit Issues 1. **Check current object count** - Review the number of objects on the affected channel - - Identify unnecessary or obsolete objects + - Default limit is 100 objects per channel + - Objects persist for 90 days by default 2. **Clean up unused objects** - Remove objects no longer needed - Implement proper cleanup in your application logic + - Consider shorter retention periods for temporary data + +3. **Optimize object usage** + - Use composable structures (nested LiveMaps) instead of many top-level objects + - Distribute objects across multiple channels if needed + - Implement object pooling for frequently created/destroyed objects -3. **Upgrade your package if needed** +4. **Upgrade your package if needed** - Contact sales to increase object limits - Review pricing plans for higher limits - Consider distributing objects across multiple channels + + ## Automatic Handling This error is not automatically retried by Ably SDKs as it indicates a configuration issue that must be resolved before the operation will succeed. @@ -113,31 +152,48 @@ This error is not automatically retried by Ably SDKs as it indicates a configura ### For Channel Encryption - Document encryption requirements for all channels - Use environment variables for cipher keys -- Test encryption configuration before deploying +- Test encryption configuration before deploying - Implement consistent key management across clients - +- Use secure key distribution mechanisms +- Never log or expose cipher keys + ### For LiveObjects - Monitor object count regularly - Implement automatic cleanup policies -- Design with limits in mind +- Design with limits in mind (100 objects default) - Use multiple channels to distribute load +- Consider object lifecycle management ## Why This Conflict Exists This error code appears to have been assigned to different features at different times: -- The Ruby SDK has historically used 92001 for channel encryption errors -- LiveObjects documentation assigns 92001 to object limit errors +- The Ruby SDK has historically used 92001 for channel encryption errors (in use for years) +- LiveObjects documentation assigns 92001 to object limit errors (newer feature) -We're working to resolve this conflict. In the meantime, use the error message and your application context to determine which scenario applies. - +This conflict may cause confusion when encountering the error. Use the error message text and your application context to determine which scenario applies. + ## Related Resources -- [Channel Encryption Documentation](https://ably.com/docs/realtime/encryption) -- [LiveObjects Documentation](https://ably.com/docs/products/liveobjects) -- [Ruby SDK Reference](https://ably.com/docs/sdks/ruby) -- Related errors: [92002](./92002), [92003](./92003), [92004](./92004), [92005](./92005) (cipher errors in Ruby SDK) +- [Channel Encryption Documentation](https://ably.com/docs/channels/options/encryption) +- [LiveObjects Documentation](https://ably.com/docs/liveobjects) +- [Ruby SDK API Reference](https://ably.com/docs/sdk/ruby/v1.2/) +- [Encryption Best Practices](https://ably.com/docs/api/realtime-sdk/encryption) + +## Related Errors + +• **[92002 - Cipher Algorithm Mismatch](https://help.ably.io/error/92002)** + Different encryption algorithms between sender and receiver + +• **[92003 - Decryption Failure](https://help.ably.io/error/92003)** + General decryption failure during message processing + +• **[92004 - Invalid Padding](https://help.ably.io/error/92004)** + Incorrect padding during decryption operation + +• **[92005 - Invalid Cipher Data](https://help.ably.io/error/92005)** + Corrupted or malformed encrypted message data ## Need Further Help? @@ -159,39 +215,46 @@ Our team will help you resolve this issue as quickly as possible. - + + + @@ -200,6 +263,6 @@ To improve this error code documentation: 1. First approach: Update editorial-notes.md in ably-os repository with specific guidance for error 92001 2. Regenerate: Run `./bin/ably-os errors document-error-codes 92001 --force` 3. For broader improvements: Review and update ably-os prompt templates -4. Context: See https://github.com/ably/ably-os/blob/main/docs/ERROR_COMMANDS_GUIDE.md +4. Context: See https://github.com/ably/ably-os/blob/5f4ba43/docs/ERROR_COMMANDS_GUIDE.md 5. Source repository: https://github.com/ably/ably-os --> \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/92002-cipher-algorithm-mismatch.mdx b/src/pages/docs/platform/errors/codes/92002-cipher-algorithm-mismatch.mdx index a92f9889c0..375721d5d8 100644 --- a/src/pages/docs/platform/errors/codes/92002-cipher-algorithm-mismatch.mdx +++ b/src/pages/docs/platform/errors/codes/92002-cipher-algorithm-mismatch.mdx @@ -1,20 +1,21 @@ - + - + # Error 92002: Cipher algorithm mismatch ## What Happened -The encryption algorithm used to encrypt a message doesn't match the algorithm configured for decryption on this channel. +The encryption algorithm used to encrypt a message doesn't match the algorithm configured for decryption on this channel, preventing the message from being decoded. ## Quick Reference @@ -24,8 +25,8 @@ The encryption algorithm used to encrypt a message doesn't match the algorithm c ## Quick Fix -- Ensure all clients on the channel use the same cipher algorithm -- Verify both sender and receiver use matching encryption settings +- Ensure all clients on the channel use identical cipher algorithms +- Verify both sender and receiver use matching encryption settings - Check that development and production environments use consistent algorithms ## Error Messages @@ -37,18 +38,23 @@ The placeholders show the actual algorithms in conflict (e.g., AES-128-CBC vs AE ## Common Causes -1. **Different algorithm configurations** (80% of cases) +1. **Different algorithm configurations** (75% of cases) - One client using AES-128-CBC, another using AES-256-CBC - Algorithm changed without updating all clients - Development vs production environment mismatch + 2. **Algorithm migration in progress** (15% of cases) - Upgrading encryption strength without coordinating all clients - Partial deployment of algorithm changes + - Receivers not yet updated to handle new algorithm + -3. **Legacy client compatibility** (5% of cases) +3. **Legacy client compatibility** (10% of cases) - Older SDK versions using different default algorithms - Mixed SDK versions in the same channel + - Outdated client configurations + ## Resolution Steps @@ -56,23 +62,26 @@ The placeholders show the actual algorithms in conflict (e.g., AES-128-CBC vs AE - Check the error message for the specific algorithms in conflict - The channel algorithm is what your current client is configured to use - The message algorithm is what was used to encrypt the received message - + 2. **Align all clients to use the same algorithm** - Choose a standard algorithm for all clients (recommend AES-256-CBC for better security) - Update cipher configuration across all applications - + - Ensure consistency across all environments (development, staging, production) + 3. **Update your cipher configuration** - - Ensure consistent cipher params across all clients - - See [Ably encryption documentation](https://ably.com/docs/realtime/encryption) for configuration details - + - Set explicit cipher parameters for consistency + - See [Ably encryption documentation](https://ably.com/docs/api/rest-sdk/encryption) for configuration details + - Verify the algorithm is properly set in your channel options + 4. **For algorithm migration** - Deploy receivers that can handle both algorithms temporarily - Update all senders to the new algorithm - Remove support for the old algorithm once migration is complete - + - Test the migration thoroughly in a non-production environment first + ## Automatic Handling @@ -84,13 +93,28 @@ This is a configuration error that will not be automatically retried. The cipher - **Document your choice**: Keep encryption configuration documented and versioned - **Test compatibility**: Verify encryption works across all client types before deployment - **Monitor for mismatches**: Set up alerts for cipher-related errors - +- **Use configuration management**: Centralize cipher configuration to avoid inconsistencies + ## Related Resources -- [Ably encryption documentation](https://ably.com/docs/realtime/encryption) -- [Cipher params configuration](https://ably.com/docs/realtime/encryption#cipher-params) -- Related errors: [92001](./92001-channel-not-configured-for-encryption.md), [92003](./92003-decryption-failure.md), [92004](./92004-unsupported-cipher-algorithm.md) +- [Ably encryption documentation](https://ably.com/docs/api/rest-sdk/encryption) +- [Cross-platform encryption guide](https://faqs.ably.com/cross-platform-symmetric-encryption-offered-by-the-libraries) +- [Status page](https://status.ably.com) + +## Related Errors + +• **[92001 - Channel not configured for encryption](https://help.ably.io/error/92001)** + Occurs when receiving encrypted messages on a non-encrypted channel + +• **[92003 - Decryption failure](https://help.ably.io/error/92003)** + Related error when the decryption key is incorrect rather than algorithm mismatch + +• **[92004 - Unsupported cipher algorithm](https://help.ably.io/error/92004)** + Happens when attempting to use an algorithm not supported by Ably SDKs + +• **[92005 - Invalid cipher argument](https://help.ably.io/error/92005)** + Results from invalid parameters passed to cipher operations ## Need Further Help? @@ -111,35 +135,38 @@ Our team will help you resolve this issue as quickly as possible. - + + + @@ -165,4 +192,5 @@ The research revealed that error 92002 is documented differently in different pl 2. Platform Docs (docs/src/pages/docs/platform/errors/codes.mdx:719): Documents 92002 as LiveObjects tombstone error This documentation focuses on the cipher algorithm mismatch as that's the only actual implementation found in the codebase. The LiveObjects documentation may be for a planned feature or documentation error. +Reference: https://github.com/ably/ably-os/blob/5f4ba43/output/error-codes/research/92002-knowledge.md lines 53-68 --> \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/92003-cipher-decryption-failed.mdx b/src/pages/docs/platform/errors/codes/92003-cipher-decryption-failed.mdx index e29747d895..b761dbbde5 100644 --- a/src/pages/docs/platform/errors/codes/92003-cipher-decryption-failed.mdx +++ b/src/pages/docs/platform/errors/codes/92003-cipher-decryption-failed.mdx @@ -1,98 +1,116 @@ - + - + # Error 92003: Cipher decryption failed ## What Happened -The SDK was unable to decrypt an encrypted message, typically because the decryption key doesn't match the key used for encryption. +The SDK was unable to decrypt an encrypted message because the decryption key or parameters don't match those used for encryption. ## Quick Reference | Error Code | HTTP Status | Category | Retryable | |------------|-------------|----------|-----------| -| 92003 | 400 | Cipher/Encryption Error | No - requires correct encryption key | +| 92003 | 400 | Client Error (Cipher/Encryption) | No - requires correct encryption configuration | ## Quick Fix -- Verify you're using the correct encryption key for this channel -- Ensure the key format matches (base64, hex, or raw) -- Check that both publisher and subscriber use identical cipher parameters +- Verify you're using the exact same encryption key on both publisher and subscriber +- Ensure key encoding matches (base64, hex, or raw bytes) +- Check that cipher parameters are identical across all clients ## Error Messages You may see one of these messages: - "CipherError decrypting data, the private key may not be correct" -- OpenSSL cipher errors indicating decryption failure +- OpenSSL cipher errors during decryption operations +- Decryption failure messages from the message encoding pipeline ## Common Causes 1. **Incorrect encryption key** (80% of cases) - - Using wrong environment's key (dev vs production) - - Key mismatch between publisher and subscriber - - Copy-paste errors when configuring keys + + - Using wrong environment's key (development vs production) + - Key mismatch between message publisher and subscriber + - Copy-paste errors when configuring encryption keys 2. **Key encoding issues** (15% of cases) - - Base64 vs hex vs raw format confusion + + - Base64 vs hex vs raw byte format confusion - Key truncation during configuration - - Character encoding problems + - Character encoding problems in key strings 3. **Key rotation without coordination** (5% of cases) - - Publisher updated to new key - - Subscriber still using old key + + - Publisher updated to new encryption key + - Subscriber still using old encryption key - Messages encrypted with different keys in same channel ## Resolution Steps 1. **Verify the encryption key** - - - Check you're using the correct key for your environment + + - Confirm you're using the correct key for your environment - Ensure the key hasn't been truncated or modified - - Confirm both publisher and subscriber have the same key + - Verify both publisher and subscriber have identical keys 2. **Check key encoding and format** - - - Verify if key should be base64, hex, or raw bytes + + - Determine if your key should be base64-encoded, hex, or raw bytes - Ensure consistent encoding across all clients - - Check for any character set conversion issues + - Validate key length matches your chosen cipher algorithm 3. **Review cipher parameters configuration** - + - Confirm algorithm matches between encryption and decryption - - Verify initialization vector (IV) handling if custom - - Check cipher mode (CBC, GCM, etc.) consistency + - Verify initialization vector (IV) handling if using custom parameters + - Check cipher mode consistency (CBC, GCM, etc.) 4. **Test with known good configuration** + - Try decrypting a test message with known parameters - - Use Ably's default cipher params as baseline - - Isolate whether issue is with specific messages or all encrypted data + - Use Ably's default cipher params as baseline for testing + - Isolate whether issue affects specific messages or all encrypted data ## Automatic Handling -This is a configuration error that SDKs cannot automatically resolve. The application must provide the correct encryption key and parameters. +This is a configuration error that SDKs cannot automatically resolve. The application must provide the correct encryption key and parameters for successful decryption. ## Prevention + - Store encryption keys securely using vault or KMS services - Implement key versioning for smooth rotation -- Test encryption/decryption in staging before production +- Test encryption/decryption in staging before production deployment - Monitor decryption failures for security alerts - Document key distribution and rotation procedures +- Consider security implications of repeated decryption failures + +## Related Errors + +• **[92002 - Cipher Algorithm Mismatch](https://help.ably.io/error/92002)** + Occurs when the encryption algorithm doesn't match between publisher and subscriber + +• **[92004 - Unsupported Cipher Algorithm](https://help.ably.io/error/92004)** + Raised when attempting to use an unsupported encryption algorithm + +• **[92005 - Invalid Cipher Arguments](https://help.ably.io/error/92005)** + Invalid parameters provided to the cipher configuration ## Related Resources -- [Encryption documentation](https://ably.com/docs/realtime/encryption) -- [Cipher parameters guide](https://ably.com/docs/realtime/encryption#cipher-params) -- Related errors: 92002 (cipher algorithm mismatch) +- [Channel encryption documentation](https://ably.com/docs/channels/options/encryption) +- [Cipher parameters guide](https://ably.com/docs/channels/options/encryption#cipher-params) +- [Security best practices](https://ably.com/docs/best-practice/security) ## Need Further Help? @@ -113,49 +131,55 @@ Our team will help you resolve this issue as quickly as possible. - + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/92004-dual-purpose-cipher-or-object-error.mdx b/src/pages/docs/platform/errors/codes/92004-dual-purpose-cipher-or-object-error.mdx index cfa4a8be5c..4f1c6879c8 100644 --- a/src/pages/docs/platform/errors/codes/92004-dual-purpose-cipher-or-object-error.mdx +++ b/src/pages/docs/platform/errors/codes/92004-dual-purpose-cipher-or-object-error.mdx @@ -1,74 +1,76 @@ - + - + -# Error 92004: Dual Purpose - Cipher Algorithm or Object Not Found +# Error 92004: Cipher Algorithm Error or Object Not Found ## What Happened -This error has two completely different meanings depending on your context: -1. **Ruby SDK**: An unsupported cipher algorithm was specified for encryption -2. **LiveObjects**: An attempt was made to access an object that doesn't exist +Error 92004 serves two distinct purposes in Ably's ecosystem: +1. **Ruby SDK Encryption**: An unsupported cipher algorithm was specified for message encryption +2. **LiveObjects**: An attempt was made to access a LiveObject that doesn't exist or has been deleted ## Quick Reference | Error Code | HTTP Status | Category | Retryable | |------------|-------------|----------|-----------| -| 92004 | 400 (Ruby SDK) or 404 (LiveObjects) | Cipher Error or Object Not Found | No - requires configuration fix | +| 92004 | 400 (Ruby) / 404 (LiveObjects) | Cipher Error / Object Not Found | No - requires configuration or state fix | ## Quick Fix -**If you're using encryption (Ruby SDK)**: -- Switch to a supported algorithm: AES-128-CBC or AES-256-CBC -- Use the SDK's default encryption settings -- Check for typos in algorithm names +**For Ruby SDK Encryption Errors**: +- Switch to a supported algorithm: `aes-128-cbc` or `aes-256-cbc` +- Use the SDK's default encryption settings (AES-256-CBC) +- Verify algorithm name spelling and format (use hyphens, not underscores) -**If you're using LiveObjects**: -- Verify the object ID exists before accessing -- Listen for object lifecycle events -- Handle deletion scenarios gracefully +**For LiveObjects Errors**: +- Verify the object exists before accessing it +- Subscribe to object lifecycle events to track deletions +- Implement proper error handling for missing objects ## Error Messages -You may see one of these messages: -- "unsupported cipher algorithm" (Ruby SDK) +You'll encounter different messages depending on the context: +- "unsupported cipher algorithm" (Ruby SDK encryption) - "unable to fetch objects tree for not found object: [object-id]" (LiveObjects) -- Dynamic error message from encryption library (Ruby SDK) +- Dynamic error message from the underlying encryption library (Ruby SDK) +- "Object not found" (LiveObjects REST API) ## Common Causes ### For Ruby SDK Encryption 1. **Unsupported algorithm specified** (90% of cases) - - Using DES, 3DES, or other deprecated algorithms - - Custom or proprietary algorithms - - Misspelled algorithm names (e.g., 'aes256cbc' instead of 'aes-256-cbc') - + - Using deprecated algorithms like DES or 3DES + - Attempting to use custom or proprietary algorithms + - Misspelled algorithm names (e.g., `aes256cbc` instead of `aes-256-cbc`) + 2. **Platform-specific algorithm names** (10% of cases) - - Using algorithm names from other libraries - - Case sensitivity issues - + - Using algorithm names from other cryptography libraries + - Format inconsistencies (missing hyphens or incorrect casing) + ### For LiveObjects 1. **Accessing deleted objects** (60% of cases) - - Object was deleted by another client - - Attempting operations on stale object references - + - Object was deleted by another client in a collaborative session + - Attempting operations on stale object references after deletion + 2. **Invalid object ID** (40% of cases) - - Typo in object identifier - - Using ID from different channel or app - + - Typo in the object identifier string + - Using an object ID from a different channel or application + - Malformed object ID format + ## Resolution Steps @@ -76,87 +78,100 @@ You may see one of these messages: 1. **Use a supported algorithm** ```ruby - # Explicitly use AES-256-CBC (recommended) + # Explicitly use AES-256-CBC (recommended for stronger security) cipher_params = Ably::Util::Crypto.get_default_params( key: your_encryption_key, algorithm: 'aes-256-cbc' ) - # Or use AES-128-CBC + # Or use AES-128-CBC for compatibility cipher_params = Ably::Util::Crypto.get_default_params( key: your_encryption_key, algorithm: 'aes-128-cbc' ) ``` - + -2. **Use SDK defaults (simplest approach)** +2. **Use SDK defaults (simplest and recommended approach)** ```ruby # Let the SDK choose the default algorithm (AES-256-CBC) cipher_params = Ably::Util::Crypto.get_default_params(key: your_encryption_key) ``` - + -3. **Verify algorithm spelling and format** - - Must use hyphens: 'aes-256-cbc' not 'aes256cbc' - - Case-insensitive in Ruby SDK - - Avoid spaces or underscores +3. **Verify algorithm naming conventions** + - Use hyphens: `aes-256-cbc` not `aes256cbc` + - The Ruby SDK accepts case-insensitive input + - Avoid spaces, underscores, or other separators + ### If Using LiveObjects -1. **Implement object lifecycle handling** +1. **Implement proper object lifecycle handling** ```javascript - // Listen for object deletion events + // Subscribe to object deletion events before accessing liveMap.subscribe('deleted', () => { console.log('Object was deleted'); - // Clean up references and UI + // Clean up local references and update UI accordingly }); ``` - + -2. **Check object existence before operations** +2. **Verify object existence before operations** ```javascript try { const object = await channel.liveObjects.get(objectId); - // Proceed with operations + // Object exists, proceed with operations } catch (error) { if (error.code === 92004) { console.log('Object does not exist'); - // Handle missing object scenario + // Handle missing object gracefully } } ``` + -3. **Retry with valid object ID** - - Verify the object ID format - - Ensure you're using the correct channel - - Check if object was created successfully +3. **Validate object references** + - Verify the object ID format matches expected pattern + - Ensure you're accessing the correct channel namespace + - Confirm the object was successfully created before accessing + ## Automatic Handling -This error is not automatically retried by Ably SDKs as it indicates a configuration or state issue that must be resolved by your application. +Ably SDKs do not automatically retry this error as it indicates either a configuration problem (encryption) or an invalid state (missing object) that requires application-level resolution. ## Prevention ### For Encryption (Ruby SDK) -- Always use SDK-provided encryption constants -- Document your encryption requirements -- Test algorithm support on all target platforms -- Prefer SDK defaults when possible - +- Use SDK-provided algorithm constants rather than string literals +- Document encryption requirements in your application configuration +- Test cipher algorithm support across all deployment platforms +- Prefer SDK defaults (AES-256-CBC) unless specific requirements exist + ### For LiveObjects -- Implement proper lifecycle event handling -- Maintain object reference validity -- Handle concurrent deletion scenarios -- Use optimistic locking patterns where appropriate +- Always subscribe to lifecycle events before object operations +- Implement reference tracking to detect stale objects +- Handle concurrent deletion scenarios in collaborative applications +- Consider using optimistic concurrency control patterns ## Related Resources -- [Ably Encryption Documentation](https://ably.com/docs/realtime/encryption) -- [LiveObjects Documentation](https://ably.com/docs/products/liveobjects) +- [Ably Encryption Documentation](https://ably.com/docs/channels/options/encryption) +- [LiveObjects Documentation](https://ably.com/docs/liveobjects) - [Ruby SDK Crypto Reference](https://github.com/ably/ably-ruby#encryption) -- Related errors: [92001](./92001-invalid-encrypted-data.md), [92003](./92003-decryption-error.md), [92005](./92005-invalid-cipher-params.md) + +## Related Errors + +• **[92001 - Invalid Encrypted Data](https://help.ably.io/error/92001)** + Occurs when decryption fails due to corrupted or incorrectly formatted encrypted data + +• **[92003 - Decryption Error](https://help.ably.io/error/92003)** + Related cipher error when the decryption key doesn't match the encryption key + +• **[92005 - Invalid Cipher Parameters](https://help.ably.io/error/92005)** + Configuration error when cipher parameters are malformed or incomplete ## Need Further Help? @@ -177,38 +192,45 @@ Our team will help you resolve this issue as quickly as possible. - + + + @@ -216,7 +238,7 @@ Our team will help you resolve this issue as quickly as possible. To improve this error code documentation: 1. First approach: Update editorial-notes.md in ably-os repository with specific guidance for error 92004 2. Regenerate: Run `./bin/ably-os errors document-error-codes 92004 --force` -3. For broader improvements: Consider splitting 92004 into two distinct error codes -4. Context: See https://github.com/ably/ably-os/blob/main/docs/ERROR_COMMANDS_GUIDE.md +3. For broader improvements: Consider splitting 92004 into two distinct error codes in future API versions +4. Context: See https://github.com/ably/ably-os/blob/5f4ba43/docs/ERROR_COMMANDS_GUIDE.md 5. Source repository: https://github.com/ably/ably-os --> \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/92005-duplicate-context-error.mdx b/src/pages/docs/platform/errors/codes/92005-duplicate-context-error.mdx index fea4b7bda6..b71acc06b3 100644 --- a/src/pages/docs/platform/errors/codes/92005-duplicate-context-error.mdx +++ b/src/pages/docs/platform/errors/codes/92005-duplicate-context-error.mdx @@ -1,20 +1,20 @@ - + -# Error 92005: Duplicate context error - cipher or LiveObjects path issue +# Error 92005: Cipher configuration error or LiveObjects path not found ## What Happened -This error code is currently used in two different contexts within Ably's systems. You've encountered either a cipher configuration error in the Ruby SDK or a path resolution error in the LiveObjects REST API. +This error code is used in two different contexts within Ably's systems. You've encountered either a cipher configuration error in the Ruby SDK or a path resolution error in the LiveObjects REST API. ## Quick Reference @@ -24,10 +24,9 @@ This error code is currently used in two different contexts within Ably's system ## Quick Fix -Identify which context applies to you: -- **Using Ruby SDK encryption?** Check your cipher key format and message data -- **Using LiveObjects REST API?** Verify the object path exists before updating -- **Unsure?** Check the error message for clues about encryption or paths +- **Using Ruby SDK encryption?** Check your cipher key format and ensure it's properly encoded +- **Using LiveObjects REST API?** Verify the object path exists before attempting updates +- **Not sure which applies?** Check your error message for mentions of "cipher", "encryption", or "path" ## Error Messages @@ -47,32 +46,32 @@ You may see one of these messages: ### If Using Ruby SDK Encryption 1. **Invalid cipher key format** (60% of cases) - + - Base64 decoding failures - Wrong key length for the algorithm (e.g., not 32 bytes for AES-256) - Malformed or corrupted key data 2. **Invalid message data** (30% of cases) - + - Non-serializable data types - Encoding conflicts - Binary data handling issues 3. **Initialization vector problems** (10% of cases) - + - Malformed IV - IV length mismatch ### If Using LiveObjects REST API 1. **Path doesn't exist** (90% of cases) - + - Attempting to update a non-existent nested element - Typo in the path specification - Object was deleted before the update 2. **Incorrect path syntax** (10% of cases) - + - Malformed path structure - Missing path separators @@ -88,7 +87,7 @@ You may see one of these messages: cipher_params = Ably::Util::Crypto.get_default_params(key: key) ``` - + 2. **Check your message data format** ```ruby @@ -98,30 +97,30 @@ You may see one of these messages: data: 'string or hash' # Must be serializable } ``` - + 3. **Test with simple data first** - Start with a plain string message - Gradually add complexity - Verify encoding consistency (use UTF-8) - + ### For LiveObjects REST API Errors 1. **Verify the object exists before updating** - First retrieve the object to confirm it exists - Check the exact path structure matches your data - + 2. **Create the object path if it doesn't exist** - Use appropriate creation operations before attempting updates - Build nested structures step by step - + 3. **Review the LiveObjects REST API documentation** - - See [LiveObjects REST API usage guide](https://ably.com/docs/liveobjects/rest-api-usage#updating-objects-by-path) + - See [LiveObjects REST API usage guide](https://ably.com/docs/liveobjects/rest-api-usage) - Pay attention to path syntax requirements - + ## Automatic Handling @@ -134,20 +133,27 @@ This is a client error that will not be automatically retried. You must fix the - Use consistent encoding throughout your application - Test encryption setup with known-good test data - Log cipher configuration details (never log keys!) for debugging - + ### For LiveObjects Users - Always check object existence before updates - Use creation operations for new paths - Implement proper error handling for path operations - + ## Related Resources -- [Ably Encryption Documentation](https://ably.com/docs/realtime/encryption) +- [Ably Encryption Documentation](https://ably.com/docs/channels/options/encryption) - [LiveObjects REST API Documentation](https://ably.com/docs/liveobjects/rest-api-usage) - [Ruby SDK Cipher Implementation](https://github.com/ably/ably-ruby/blob/main/lib/ably/models/message_encoders/cipher.rb) -- Related cipher errors: 92003 (decryption error), 92004 (unsupported algorithm) + +## Related Errors + +• **[92003 - Cipher Decryption Error](https://help.ably.io/error/92003)** + Related cipher error occurring during message decryption operations + +• **[92004 - Unsupported Cipher Algorithm](https://help.ably.io/error/92004)** + Related cipher error when using an unsupported encryption algorithm ## Need Further Help? @@ -169,11 +175,10 @@ Our team will help you resolve this issue as quickly as possible. + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/92100-encoding-value-too-long.mdx b/src/pages/docs/platform/errors/codes/92100-encoding-value-too-long.mdx index 1fad0ad3fb..9329e46705 100644 --- a/src/pages/docs/platform/errors/codes/92100-encoding-value-too-long.mdx +++ b/src/pages/docs/platform/errors/codes/92100-encoding-value-too-long.mdx @@ -1,11 +1,11 @@ - + @@ -25,7 +25,7 @@ The message encoding metadata string exceeded the maximum allowed length of 512 ## Quick Fix - Reduce the number of encoding transformations applied to your message -- Avoid encoding already-encoded data +- Avoid encoding already-encoded data - Use only essential encoding steps for your use case ## Error Messages @@ -40,19 +40,20 @@ The `{encoding}` shows the actual encoding string that exceeded the limit. 1. **Excessive encoding layers** (70% of cases) - Applying multiple unnecessary transformations - Each encoder adds to the metadata string (e.g., `json/utf-8/base64/cipher+aes-256-cbc/gzip`) - + - The encoding chain grows with each transformation applied + 2. **Recursive encoding** (20% of cases) - Encoding already-encoded messages - Double-encoding JSON data - Processing the same message through encoders multiple times - + 3. **Unnecessary transformations** (10% of cases) - Including redundant base64 encoding - Multiple compression layers - Using both encryption and encoding when only one is needed - + ## Resolution Steps @@ -60,30 +61,30 @@ The `{encoding}` shows the actual encoding string that exceeded the limit. - Check which encodings are being applied to your messages - The encoding string concatenates all transformations with '/' separator - Example problematic chain: `json/utf-8/base64/cipher+aes-256-cbc/gzip/base64` - + 2. **Reduce encoding layers** - Use only the essential encodings for your use case - Avoid encoding data that's already in the correct format - Choose either compression or encryption, not necessarily both - + 3. **Optimize your message structure** - Apply compression before encryption if using both - Use efficient serialization formats - Consider sending raw data when appropriate - + 4. **Monitor encoding chain length** - Keep track of the encoding metadata string length - Remember the 512 character limit includes all transformation identifiers - Test with production-like data to catch issues early - + ## Automatic Handling This is a client-side validation error that occurs before the message is sent to Ably servers. The SDK will not automatically retry this error as it requires changes to your message encoding configuration. - + ## Prevention @@ -92,7 +93,7 @@ This is a client-side validation error that occurs before the message is sent to - Choose the most efficient transformation order - Document your encoding requirements to prevent unnecessary additions - Regularly review and optimize your encoding pipeline - + ## Performance Impact @@ -101,13 +102,21 @@ Long encoding chains impact your application by: - Increasing message size and bandwidth usage - Adding latency to publish and subscribe operations - Consuming more CPU for encoding/decoding - + + +## Related Errors + +• **[92001 - Encoding Error](https://help.ably.io/error/92001)** + General encoding failures during message transformation + +• **[92005 - Decoding Error](https://help.ably.io/error/92005)** + Issues when attempting to decode received messages ## Related Resources -- [Message encoding documentation](https://ably.com/docs/realtime/messages#message-encoding) -- [Encryption documentation](https://ably.com/docs/realtime/encryption) -- Related errors: [92001](./92001-encoding-error.md), [92005](./92005-decoding-error.md) +- [Message concepts documentation](https://ably.com/docs/messages/) +- [Encryption documentation](https://ably.com/docs/channels/options/encryption) +- [API Reference - Messages](https://ably.com/docs/api/rest-sdk/messages) ## Need Further Help? @@ -128,41 +137,45 @@ Our team will help you resolve this issue as quickly as possible. - + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/93001-annotations-channel-state-invalid.mdx b/src/pages/docs/platform/errors/codes/93001-annotations-channel-state-invalid.mdx index 7966972f99..b10eeea805 100644 --- a/src/pages/docs/platform/errors/codes/93001-annotations-channel-state-invalid.mdx +++ b/src/pages/docs/platform/errors/codes/93001-annotations-channel-state-invalid.mdx @@ -1,13 +1,13 @@ - + - + # Error 93001: Annotations channel state invalid @@ -39,15 +39,18 @@ You'll see this message: - Attempting annotations operations immediately after getting channel reference - Channel is still in 'initialized' or 'attaching' state - Not waiting for attachment to complete + 2. **Channel in error state** - Channel is in 'suspended', 'failed', or 'detached' state - Previous connection error not resolved - Channel attachment failed + 3. **Premature operation** - Race condition between attachment and annotations operation - Not using proper event handlers for state transitions + ## Resolution Steps @@ -61,7 +64,7 @@ You'll see this message: console.log('Annotation received:', annotation); }); ``` - + 2. **Check channel state before operations** ```javascript @@ -75,7 +78,7 @@ You'll see this message: }); } ``` - + 3. **Handle attachment with callbacks** ```javascript @@ -89,7 +92,7 @@ You'll see this message: channel.annotations.subscribe(); }); ``` - + 4. **Monitor channel state changes** ```javascript @@ -100,7 +103,12 @@ You'll see this message: channel.on('detached', () => { console.log('Channel detached - annotations unavailable'); }); + + channel.on('failed', () => { + console.log('Channel failed - recreate connection'); + }); ``` + ## Automatic Handling @@ -149,56 +157,70 @@ async function setupAnnotations() { setupAnnotations(); ``` - + ## Related Resources -- [Channel state documentation](https://ably.com/docs/realtime/channels#channel-states) -- [Channel lifecycle events](https://ably.com/docs/realtime/channels#channel-lifecycle) -- Related errors: [91004](https://help.ably.io/error/91004) (Presence state error) +- [Channel state documentation](https://ably.com/docs/channels) +- [Channel lifecycle events](https://ably.com/docs/channels) + +## Related Errors + +• **[91004 - Presence State Invalid](https://help.ably.io/error/91004)** + Similar state requirements for presence operations on channels + +• **[90001 - Channel Operation Failed](https://help.ably.io/error/90001)** + General channel operation failures that may occur alongside state issues + +• **[80000 - Connection Failed](https://help.ably.io/error/80000)** + Connection failures that prevent channels from attaching ## Need Further Help? -This error code has limited documentation available. If you encounter this error, please contact Ably support at https://ably.com/support with: -- The full error message including error code 93001 -- What action triggered the error +If you're still experiencing issues after trying these steps, our support team is here to help. + +**Contact Ably Support**: https://ably.com/support + +When contacting support, please provide: - Your account ID and app ID -- The SDK and version you're using +- The full error message including error code 93001 +- Steps to reproduce the issue - Any relevant code snippets (without sensitive credentials) +- The SDK and version you're using -Our support team will help you resolve this issue as quickly as possible. +Our team will help you resolve this issue as quickly as possible. - + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/93002-mutable-messages-feature-required.mdx b/src/pages/docs/platform/errors/codes/93002-mutable-messages-feature-required.mdx index b0cbd67a66..ddbb274fd9 100644 --- a/src/pages/docs/platform/errors/codes/93002-mutable-messages-feature-required.mdx +++ b/src/pages/docs/platform/errors/codes/93002-mutable-messages-feature-required.mdx @@ -1,20 +1,20 @@ - + - + # Error 93002: Mutable Messages feature required ## What Happened -The operation you're attempting requires the Mutable Messages feature to be enabled, but it's not currently available on this channel. +The operation you're attempting requires the Mutable Messages feature to be enabled for this channel's namespace, but it's not currently activated. ## Quick Reference @@ -26,7 +26,7 @@ The operation you're attempting requires the Mutable Messages feature to be enab - Verify the Mutable Messages feature is enabled for your account - Check you're using the correct app with the feature enabled -- Contact Ably support to enable this feature if needed +- Contact Ably support at https://ably.com/support to enable this feature ## Error Messages @@ -36,63 +36,93 @@ You may see one of these messages: ## Common Causes -1. **Feature not enabled** (80% of cases) +1. **Feature not enabled at namespace level** (80% of cases) - Mutable Messages feature not activated for your account - - Using an app that doesn't have the feature enabled - - Feature not configured for the specific namespace + - Using an app that doesn't have the feature enabled in its namespace + - Feature not configured for the specific namespace you're using + -2. **Using annotation operations** (15% of cases) - - Attempting to subscribe to message annotations +2. **Using annotation operations without feature** (15% of cases) + - Attempting to subscribe to message annotations (`ANNOTATION_SUBSCRIBE` mode) - Publishing messages with annotations - - Using message editing capabilities + - Using message editing or reaction capabilities + -3. **Wrong environment** (5% of cases) - - Development environment has feature, production doesn't - - Using incorrect app credentials +3. **Environment configuration mismatch** (5% of cases) + - Development environment has feature enabled, production doesn't + - Using incorrect app credentials for the environment + - Migration from non-mutable to mutable namespace incomplete + ## Resolution Steps 1. **Verify feature availability** - Check your Ably dashboard for available features - Confirm your account plan includes Mutable Messages - - Verify which apps have the feature enabled - + - Verify which apps and namespaces have the feature enabled + - Test with a simple annotation operation to confirm status + 2. **Enable the feature** - Contact Ably support at https://ably.com/support - - Specify which apps need the Mutable Messages feature - - Provide your account ID and use case requirements - + - Specify which apps and namespaces need the Mutable Messages feature + - Provide your account ID, app ID, and use case requirements + - Test in staging environment first before production enablement + -3. **Use the correct app** +3. **Use the correct app and namespace** - Ensure you're using API keys from an app with the feature enabled + - Verify the channel namespace has Mutable Messages activated - Double-check environment variables and configuration - - Test the connection with a simple annotation operation + - Confirm namespace settings match your requirements + 4. **Alternative approaches if feature unavailable** - Use separate channels for metadata instead of annotations - Implement application-level annotation logic - Store annotations in an external database - Use standard message metadata fields for additional data - + - Consider message history with external tracking for edits + ## Automatic Handling -This is a feature availability error that will not be automatically retried. The Mutable Messages feature must be enabled at the account level before operations requiring it will succeed. +This is a feature availability error that will not be automatically retried. The Mutable Messages feature must be enabled at the namespace level before operations requiring it will succeed. SDKs will not attempt to retry this error as it indicates a configuration requirement rather than a transient issue. + ## Prevention -- Document which features your application requires +- Document which features your application requires during development - Test feature availability in development environments first - Plan for graceful degradation if the feature is unavailable - Consider fallback strategies for environments without the feature - +- Check namespace configuration before attempting annotation operations +- Implement feature detection in your application initialization + + +## What Requires Mutable Messages + +The following operations require the Mutable Messages feature: +- Annotation subscriptions on channels +- Publishing messages with annotations +- Message editing capabilities +- Message reaction features +- Any operation that modifies message content after publishing + ## Related Resources - [Ably Support](https://ably.com/support) - Contact for feature enablement - [Ably Dashboard](https://ably.com/dashboard) - Check your account features -- [Ably Pricing](https://ably.com/pricing) - View plan features +- [Ably Pricing](https://ably.com/pricing) - View plan features and capabilities + +## Related Errors + +• **[40140 - Token expired](https://help.ably.io/error/40140)** + May occur alongside 93002 if authentication issues prevent feature verification + +• **[90001 - Channel operation failed](https://help.ably.io/error/90001)** + General channel operation failure that may indicate broader configuration issues ## Need Further Help? @@ -113,50 +143,55 @@ Our team will help you resolve this issue as quickly as possible. - + + + \ No newline at end of file From 869b7c678d4106640cff738b37c4bfa302221732 Mon Sep 17 00:00:00 2001 From: Matthew O'Riordan Date: Tue, 2 Sep 2025 10:14:17 +0200 Subject: [PATCH 6/6] Updated a sample of docs based on Paddy feedback See https://github.com/ably/ably-os/pull/3#issuecomment-3241253224 --- .../codes/40008-invalid-content-length.mdx | 233 ++++++------- .../codes/40010-invalid-channel-name.mdx | 312 +++++------------- .../codes/40013-data-encoding-failed.mdx | 164 +++++++++ ...40013-invalid-message-data-or-encoding.mdx | 267 --------------- .../codes/92100-encoding-string-too-long.mdx | 132 ++++++++ .../codes/92100-encoding-value-too-long.mdx | 191 ----------- 6 files changed, 486 insertions(+), 813 deletions(-) create mode 100644 src/pages/docs/platform/errors/codes/40013-data-encoding-failed.mdx delete mode 100644 src/pages/docs/platform/errors/codes/40013-invalid-message-data-or-encoding.mdx create mode 100644 src/pages/docs/platform/errors/codes/92100-encoding-string-too-long.mdx delete mode 100644 src/pages/docs/platform/errors/codes/92100-encoding-value-too-long.mdx diff --git a/src/pages/docs/platform/errors/codes/40008-invalid-content-length.mdx b/src/pages/docs/platform/errors/codes/40008-invalid-content-length.mdx index 1fe4dda6a4..5a94f7b4da 100644 --- a/src/pages/docs/platform/errors/codes/40008-invalid-content-length.mdx +++ b/src/pages/docs/platform/errors/codes/40008-invalid-content-length.mdx @@ -1,131 +1,115 @@ - + - + # Error 40008: Invalid content length ## What Happened -The server detected that your HTTP request body contains more data than specified in the Content-Length header, indicating a mismatch between the declared and actual request size. +The request body contains more bytes than specified in the Content-Length header. ## Quick Reference | Error Code | HTTP Status | Category | Retryable | |------------|-------------|----------|-----------| -| 40008 | 400 | Client Error (Request Validation) | No - requires fixing the request | - -## Quick Fix - -- Let your HTTP client automatically calculate the Content-Length header -- Verify no proxy or middleware is modifying your request body -- For streaming data, consider using chunked transfer encoding instead - -## Error Messages - -You'll encounter this message: -- "Invalid content length" - -## Common Causes - -1. **Content-Length header exceeds actual data** (80% of cases) - - - The declared Content-Length is larger than the data actually sent - - Server receives more data than the Content-Length header indicates - - Typically happens when manually calculating content length incorrectly - -2. **HTTP client misconfiguration** (15% of cases) - - Manual Content-Length header setting with incorrect byte count - - Character encoding differences affecting byte calculations - - Multi-byte UTF-8 characters counted as single bytes - -3. **Network or proxy interference** (5% of cases) - - Intermediate proxy modifying request body - - Middleware altering content after header is set - - Request body transformation without header update - -## Resolution Steps - -1. **Allow automatic Content-Length calculation** - - ```javascript - // ✅ Correct: Let the HTTP client handle headers - fetch('https://rest.ably.io/channels/my-channel/messages', { - method: 'POST', - headers: { - 'Authorization': 'Basic ' + apiKey, - 'Content-Type': 'application/json' - // Do NOT manually set Content-Length - }, - body: JSON.stringify(messageData) - }); - - // ❌ Wrong: Manual Content-Length can cause mismatches - fetch('https://rest.ably.io/channels/my-channel/messages', { - method: 'POST', - headers: { - 'Content-Length': '123', // Avoid this - 'Content-Type': 'application/json' - }, - body: JSON.stringify(messageData) - }); - ``` - -2. **If manual Content-Length is required, calculate bytes correctly** - - ```javascript - // Calculate byte length, not character length - const body = JSON.stringify(data); - const byteLength = new TextEncoder().encode(body).length; - // Use byteLength for Content-Length, not body.length - ``` - -3. **Use chunked transfer encoding for dynamic content** - - - Set `Transfer-Encoding: chunked` header - - Omit Content-Length header entirely - - Suitable for streaming or dynamically generated content - -4. **Debug request flow** - - Log Content-Length header value and actual body size - - Check for middleware or proxies that might modify requests - - Use network debugging tools to inspect the raw HTTP request - -## Automatic Handling - -This client error is not automatically retried by Ably SDKs. The request validation fails immediately when the server detects more data than declared in the Content-Length header. +| 40008 | 400 | Client Error (Validation) | No - requires fixing the request | + +## Troubleshooting + +### Content-Length Mismatch +**Symptom**: "Invalid content length: received X bytes but Content-Length header specified Y bytes" +**Solution**: +- Calculate Content-Length using byte length, not character count +- Use `Buffer.byteLength()` in Node.js or equivalent in your language +- For dynamic content, consider using chunked transfer encoding instead + + + +### Multi-byte Character Issues +**Symptom**: Error occurs when sending non-ASCII characters (emojis, accented characters) +**Solution**: +- Always calculate byte length, not string length +- UTF-8 characters can be 1-4 bytes each +- Example: "Hello 👋" is 10 bytes, not 7 characters + + + +### HTTP Client Library Issues +**Symptom**: Content-Length is automatically set incorrectly by your HTTP client +**Solution**: +- Update to the latest version of your HTTP client library +- Verify the library correctly handles Content-Length for your use case +- Consider switching to a well-maintained HTTP client if issues persist + + + +### Proxy or Middleware Interference +**Symptom**: Error occurs in production but not in development +**Solution**: +- Check if any proxies or middleware are modifying the request body +- Ensure all intermediate systems preserve Content-Length accuracy +- Review logs from load balancers or API gateways + + + +## Code Examples + +### Correct Content-Length Calculation +```javascript +// ✅ Correct: Use byte length for Content-Length +const body = JSON.stringify({ message: 'Hello 世界' }); +const request = { + method: 'POST', + headers: { + 'Content-Type': 'application/json', + 'Content-Length': Buffer.byteLength(body) // Correct byte calculation + }, + body: body +}; + +// ❌ Wrong: Using string length +const incorrectLength = body.length; // This counts characters, not bytes +``` + + +### Using Chunked Transfer Encoding +For dynamic content where the final size is unknown, use chunked transfer encoding: +```javascript +// Most modern HTTP clients handle this automatically +const request = { + method: 'POST', + headers: { + 'Content-Type': 'application/json', + 'Transfer-Encoding': 'chunked' + // No Content-Length header needed + }, + body: streamOfData +}; +``` + ## Prevention -- **Use Ably SDKs**: Official SDKs handle all HTTP headers correctly -- **HTTP client libraries**: Use mature libraries that manage headers automatically -- **Avoid manual headers**: Don't set Content-Length unless absolutely necessary -- **Test thoroughly**: Validate with various payload sizes and character encodings -- **Monitor production**: Track this error to identify problematic client implementations +- Always calculate Content-Length using byte length functions appropriate for your language +- Test with multi-byte characters (emojis, non-Latin scripts) during development +- Consider using chunked transfer encoding for streaming or dynamic content +- Keep HTTP client libraries up to date ## Related Errors • **[40009 - Max Content Length Exceeded](https://help.ably.io/error/40009)** - Occurs when the request body exceeds Ably's maximum size limits + Occurs when the request body exceeds the maximum allowed size limit • **[40000 - Bad Request](https://help.ably.io/error/40000)** - General request validation errors that may include body format issues - -• **[40003 - Invalid Request Body](https://help.ably.io/error/40003)** - Request body parsing or format validation failures - -## Related Resources - -- [Ably REST API documentation](https://ably.com/docs/rest) -- [HTTP request limits](https://ably.com/docs/general/limits) -- [Ably SDKs](https://ably.com/download) - Recommended to avoid manual HTTP handling + General validation error for malformed requests ## Need Further Help? @@ -147,45 +131,42 @@ Our team will help you resolve this issue as quickly as possible. - - - + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/40010-invalid-channel-name.mdx b/src/pages/docs/platform/errors/codes/40010-invalid-channel-name.mdx index 5b211b9058..14e2dc4b61 100644 --- a/src/pages/docs/platform/errors/codes/40010-invalid-channel-name.mdx +++ b/src/pages/docs/platform/errors/codes/40010-invalid-channel-name.mdx @@ -1,222 +1,88 @@ - + - + # Error 40010: Invalid channel name ## What Happened -The channel name you provided doesn't meet Ably's naming requirements or contains invalid characters or qualifiers. +The channel name or qualifier you provided doesn't meet Ably's validation requirements. ## Quick Reference | Error Code | HTTP Status | Category | Retryable | |------------|-------------|----------|-----------| -| 40010 | 400 | Client Error (Channel) | No - requires fixing the channel name | - -## Quick Fix - -- Remove any square brackets `[` from the start of your channel name -- Ensure your channel name isn't empty or contains only special characters like `:` -- Check that you're not mixing incompatible channel qualifiers -- Validate channel names match the expected format for your use case - -## Error Messages - -You may see one of these messages: -- "Invalid channel name" -- "regex match failed" -- "cannot use a derived option with a {type} channel" -- "unable to attach to channel; invalid channel name" -- "Invalid qualifier in channelId; {qualifier}" -- "resource: invalid name {name}" -- "resource: invalid directive {directive}" -- "resource: invalid scope {scope}" -- "resource: invalid qualifier {qualifier}" - -## Common Causes - -1. **Channel name starts with square brackets** (60% of cases) - - - Using `[` at the beginning of the channel name - - Square brackets are reserved for channel qualifiers - - Example: `[mychannel]` instead of `mychannel` - -2. **Empty or invalid channel names** (20% of cases) - - - Using just `:` as a channel name - - Empty channel names - - Channel names with only special characters like `:::` - -3. **Incompatible channel qualifiers** (15% of cases) - - - Trying to use derived options with already-qualified channels - - Using qualifiers that don't support client attachment - - Mixing incompatible qualifier types - -4. **Malformed resource identifiers** (5% of cases) - - - Invalid scope format in resource IDs - - Invalid directives in resource names - - Malformed qualifier strings - -## Resolution Steps - -1. **Fix channel names starting with square brackets** - - ```javascript - // ❌ Wrong: Square brackets at the start - const channel = ably.channels.get('[mychannel]'); - const channel = ably.channels.get('[chat-room]'); - - // ✅ Correct: No leading square brackets - const channel = ably.channels.get('mychannel'); - const channel = ably.channels.get('chat-room'); - - // ✅ Correct: Proper qualifier syntax - const metaChannel = ably.channels.get('[meta]mychannel'); - const filteredChannel = ably.channels.get('[filter=headers.user==123]mychannel'); - ``` - -2. **Ensure channel names are valid** - - ```javascript - // ❌ Wrong: Empty or special character only names - const channel1 = ably.channels.get(':'); - const channel2 = ably.channels.get(''); - const channel3 = ably.channels.get(':::'); - - // ✅ Correct: Valid channel names - const channel1 = ably.channels.get('chat-room'); - const channel2 = ably.channels.get('user-123-updates'); - const channel3 = ably.channels.get('channel with spaces'); // Spaces are allowed - const channel4 = ably.channels.get('私のチャンネル'); // Unicode characters allowed - ``` - -3. **Use channel qualifiers correctly** - - ```javascript - // ❌ Wrong: Mixing incompatible qualifiers or incorrect syntax - // Don't try to add derived options to already-qualified channels - const wrongChannel = ably.channels.get('[meta][filter]channel'); - - // ✅ Correct: Use qualifiers as documented - const metaChannel = ably.channels.get('[meta]channel'); - const filteredChannel = ably.channels.get('[filter=headers.user-id==123]channel'); - const persistedChannel = ably.channels.get('[persisted]channel'); - - // ✅ Correct: Channel options for derived channels - const derivedChannel = ably.channels.getDerived('baseChannel', { - filter: 'headers.user-id==123' - }); - ``` - -4. **Validate channel names before use** - - ```javascript - function validateChannelName(name) { - // Channel names cannot start with '[' - if (name.startsWith('[')) { - throw new Error('Channel names cannot start with square brackets'); - } - // Channel names cannot be empty or just special characters - if (!name || name === ':' || /^:+$/.test(name)) { - throw new Error('Invalid channel name: cannot be empty or only colons'); - } - return true; - } - - try { - const channelName = getUserInput(); - validateChannelName(channelName); - const channel = ably.channels.get(channelName); - } catch (error) { - console.error('Invalid channel name:', error.message); - } - ``` - -5. **Handle third-party integration channel names** - - If you're integrating with services like PubNub or other messaging platforms, transform their channel names to meet Ably's requirements: - ```javascript - // Transform channel names from other services - function transformChannelName(externalName) { - // Remove leading brackets if present - let ablyName = externalName.replace(/^\[/, ''); - - // Remove or replace invalid patterns - ablyName = ablyName.replace(/^:+$/, 'default-channel'); - - // Ensure it's not empty - if (!ablyName) { - ablyName = 'default-channel'; - } - - return ablyName; - } - - // Example with PubNub channel name format - const pubNubChannel = 'LANGUAGE_CHANNEL-ed9b69aa-f0c5-45ae-a80e-298c6c7e82a2'; - const ablyChannel = transformChannelName(pubNubChannel); - ``` - -## Automatic Handling - -This is a client error that will not be automatically retried. You must fix the channel name format before the operation will succeed. The SDK will not attempt to correct invalid channel names automatically. - -## Channel Naming Rules - - -According to Ably's channel naming requirements: -- **Allowed**: Any Unicode character, including spaces and non-ASCII characters -- **NOT allowed**: Channel names starting with square brackets `[` -- **Reserved**: Square brackets are reserved for channel qualifiers (metadata/instructions to Ably) -- **Invalid**: Empty channel names or names consisting only of special characters like `:` or `:::` - -### Valid Channel Qualifiers -- `[meta]` - Metadata channel for channel lifecycle events -- `[filter]` - Filter messages based on headers or attributes -- `[persisted]` - Enable message persistence -- `[?rewind=]` - Replay last n messages or time period - -For complete channel naming documentation, see [Channel naming documentation](https://ably.com/docs/channels#name-syntax). - -## Prevention - -- **Input Validation**: Always validate user-provided channel names before using them -- **Third-Party Integration**: Transform external service channel names to meet Ably's requirements -- **Naming Convention**: Use consistent naming patterns across your application -- **Namespacing**: Consider using namespaces to organize channels (e.g., `chat:room-123`, `presence:user-456`) -- **Testing**: Include channel name validation in your test suite - -## Related Resources - -- [Channel documentation](https://ably.com/docs/channels) -- [Channel qualifiers](https://ably.com/docs/channels#qualifiers) -- [Channel naming restrictions](https://knowledge.ably.com/what-restrictions-are-there-on-channel-names) -- [Channel options and parameters](https://ably.com/docs/channels#options) +| 40010 | 400 | Client Error (Channel Validation) | No - requires fixing the channel name | + +## Troubleshooting + +### Malformed Channel Qualifier +**Symptom**: "Invalid channel name" or "Invalid qualifier in channelId" +**Solution**: Fix the qualifier syntax - ensure proper bracket formatting + + +Valid qualifiers use this format: `[qualifier]channel-name` +- `[meta]my-channel` - Channel metadata namespace +- `[presence]my-channel` - Presence operations +- `[-persisted]my-channel` - Non-persisted messages +- `[?rewind=10]my-channel` - Channel options + +### Missing Channel Name After Qualifier +**Symptom**: Channel name is empty after the qualifier +**Solution**: Add a channel name after the qualifier + + +```javascript +// ❌ Wrong: No channel name after qualifier +channel = realtime.channels.get('[meta]'); + +// ✅ Correct: Channel name included +channel = realtime.channels.get('[meta]my-channel'); +``` + + +### Channel Names Starting with Square Bracket +**Symptom**: Channel name starts with `[` but isn't a valid qualifier +**Solution**: Either use proper qualifier syntax or avoid starting with `[` + + +Square brackets are reserved for channel metadata and instructions. See [Channel documentation](https://ably.com/docs/channels) for allowed patterns. + +### Incompatible Channel Options +**Symptom**: "cannot use a derived option with a {type} channel" +**Solution**: Don't apply derived options to already-qualified channels + + +```javascript +// ❌ Wrong: Applying options to qualified channel +const qualified = realtime.channels.get('[meta]channel'); +qualified.setOptions({ params: { rewind: '1' } }); + +// ✅ Correct: Include options at channel creation +const channel = realtime.channels.get('[?rewind=1]my-channel'); +``` + + +### PubNub Protocol Translation Issues +**Symptom**: Error occurs with channels from PubNub translator +**Solution**: Ensure channel names are compatible with Ably's format when migrating from PubNub + ## Related Errors • **[40000 - Bad Request](https://help.ably.io/error/40000)** - General client error that may occur with other invalid request parameters - -• **[40400 - Not Found](https://help.ably.io/error/40400)** - Occurs when referencing a channel that doesn't exist in certain contexts + General request validation errors that may include channel issues • **[90000 - Channel Operation Failed](https://help.ably.io/error/90000)** - Related channel operation failures that may cascade from invalid names - -• **[91000 - Unable to Enter Presence](https://help.ably.io/error/91000)** - May occur if trying to enter presence on a channel with an invalid name + Channel operations that fail for reasons beyond naming ## Need Further Help? @@ -237,52 +103,40 @@ Our team will help you resolve this issue as quickly as possible. - + + + - - - \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/40013-data-encoding-failed.mdx b/src/pages/docs/platform/errors/codes/40013-data-encoding-failed.mdx new file mode 100644 index 0000000000..aef8f42b4f --- /dev/null +++ b/src/pages/docs/platform/errors/codes/40013-data-encoding-failed.mdx @@ -0,0 +1,164 @@ + + + + + + + + +# Error 40013: Data encoding failed + +## What Happened + +Your message data could not be encoded or decoded due to an unsupported data type, incorrect message format, or encoding processing failure. + +## Quick Reference + +| Error Code | HTTP Status | Category | Retryable | +|------------|-------------|----------|-----------| +| 40013 | 400 | Client Error (Message Validation) | No - requires fixing data format | + +## Troubleshooting + +### Unsupported Data Type +**Symptom**: "Data type is unsupported" error when publishing + +**Solution**: Convert your data to a supported type before publishing: + +**JavaScript/TypeScript** - Supported: String, Buffer, Object, Array, null +```javascript +// ❌ Wrong: Publishing a number directly +channel.publish('event', 42); + +// ✅ Correct: Convert to string or wrap in object +channel.publish('event', '42'); +channel.publish('event', { value: 42 }); +``` + +**Ruby** - Supported: String, Hash, Array, nil +```ruby +# ❌ Wrong: Publishing unsupported type +channel.publish('event', 123) + +# ✅ Correct: Convert to supported type +channel.publish('event', '123') +channel.publish('event', { value: 123 }) +``` + + +### Invalid Single-Argument Format +**Symptom**: "The single-argument form of publish() expects a message object or an array of message objects" + +**Solution**: Use the correct publish format: +```javascript +// ❌ Wrong: Invalid single argument +channel.publish('just a string'); + +// ✅ Correct: Two arguments or message object +channel.publish('event', 'just a string'); +channel.publish({ name: 'event', data: 'just a string' }); +``` + +### Encryption/Decryption Failures +**Symptom**: "Error processing the cipher encoding" often after idle periods + +**Solution**: Ensure encryption keys are consistent between publisher and subscriber: +```javascript +// Ensure both publisher and subscriber use the same key +const cipherKey = 'your-consistent-base64-key'; +const channel = realtime.channels.get('secure', { + cipher: { key: cipherKey } +}); +``` + + +### Encoding Chain Processing +**Symptom**: "Invalid data type for 'base64' decoding" or "unknown encoding" + +**Solution**: Verify data matches the encoding requirements - base64 needs strings, JSON needs objects/arrays. + +### LiveObjects Map Validation +**Symptom**: "Map value data type is unsupported" when using LiveObjects + +**Solution**: Use only primitive or JSON-serializable values in LiveMap. + +## Prevention + +- Always validate data types match your SDK's supported types before publishing +- Use consistent cipher keys across all publishers and subscribers +- For React/Vue applications, memoize channel names to prevent race conditions + +- Handle promise rejections when publishing to avoid script exits in Node.js + + +## Related Errors + +• **[40140 - Token Expired](https://help.ably.io/error/40140)** + Token issues that may affect encrypted channel authentication + +• **[92001 - Encryption Configuration Error](https://help.ably.io/error/92001)** + Cipher parameter configuration issues + +## Need Further Help? + +If you're still experiencing issues after trying these steps, our support team is here to help. + +**Contact Ably Support**: https://ably.com/support + +When contacting support, please provide: +- Your account ID and app ID +- The full error message including error code 40013 +- Steps to reproduce the issue +- Any relevant code snippets (without sensitive credentials) +- The SDK and version you're using + +Our team will help you resolve this issue as quickly as possible. + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/40013-invalid-message-data-or-encoding.mdx b/src/pages/docs/platform/errors/codes/40013-invalid-message-data-or-encoding.mdx deleted file mode 100644 index 03eae76078..0000000000 --- a/src/pages/docs/platform/errors/codes/40013-invalid-message-data-or-encoding.mdx +++ /dev/null @@ -1,267 +0,0 @@ - - - - - - - - -# Error 40013: Invalid message data or encoding - -## What Happened - -The SDK cannot encode or decode your message because the data type is unsupported or the encoding process failed. - -## Quick Reference - -| Error Code | HTTP Status | Category | Retryable | -|------------|-------------|----------|-----------| -| 40013 | 400 | Client Error (Message Processing) | No - requires fixing the data format | - -## Quick Fix - -- Ensure message data is a string, buffer, JSON-serializable object, or array -- For encrypted channels, verify cipher configuration is consistent across clients -- Consider marshalling complex data as JSON before publishing -- Check for race conditions with dynamically constructed channel names - -## Error Messages - -You may see one of these messages: -- "Data type is unsupported" -- "Invalid message data or encoding" -- "The single-argument form of publish() expects a message object or an array of message objects" -- "Map value data type is unsupported" (LiveObjects) -- "Invalid data type for 'base64' decoding" -- "Invalid data type for 'json' decoding" -- "Invalid data type for 'utf-8' decoding" -- "decrypt failed" -- "Error processing the {encoding} encoding, decoder returned '{error}'" -- "Invalid cipher message data; unexpected length: {}" (Rust) -- "unknown encoding: '{encoding}'" - -## Common Causes - -1. **Unsupported data types** (60% of cases) - - - Publishing objects that aren't JSON-serializable - - Using LiveObjects with unsupported value types - - Passing wrong argument types to publish() - - Platform-specific type mismatches (e.g., NSString vs NSData in iOS) - -2. **Encryption/decryption failures** (30% of cases) - - - Cipher configuration mismatch between clients - - Decryption failures after channel idle periods - - Race conditions with encryption key handling - - Inconsistent encryption for presence vs message data - -3. **Encoding chain failures** (10% of cases) - - - Invalid base64 data - - Malformed JSON strings - - UTF-8 encoding of binary data - - Cipher block alignment issues (Rust SDK) - -## Resolution Steps - -1. **Validate your message data type** - - - Supported types vary by SDK: - - **JavaScript**: String, Buffer, JSON-serializable objects/arrays - - **Ruby**: String, Hash, Array, or nil - - **iOS/macOS**: NSString, NSData, NSArray, NSDictionary - - **Java**: String, byte[], JsonElement - - **Rust**: Types that implement Serialize trait - - For complex objects, serialize to JSON first: - ```javascript - // ❌ Wrong: Publishing non-serializable object - channel.publish('update', myComplexObject); - - // ✅ Correct: Serialize to JSON first - channel.publish('update', JSON.stringify(myComplexObject)); - ``` - - -2. **Fix publish() method arguments** (JavaScript SDKs) - - - ```javascript - // ❌ Wrong: Invalid single argument - channel.publish('not-a-message-object'); - - // ✅ Correct: Use message object - channel.publish({ name: 'event', data: 'payload' }); - - // ✅ Correct: Or use name and data arguments - channel.publish('event', 'payload'); - ``` - - -3. **Verify encryption configuration** - - - If using encrypted channels, ensure all clients use identical cipher configuration: - ```javascript - // All clients must use the same key and options - const cipherKey = await generateKey(); - const channel = ably.channels.get('encrypted-channel', { - cipher: { key: cipherKey } - }); - - // For dynamic channel names, memoize to avoid race conditions - const channelName = getChannelName(); // Memoize this! - const channel = ably.channels.get(channelName, { cipher: { key } }); - ``` - - -4. **Handle LiveObjects data types** - - - For LiveObjects, only use supported types: - ```javascript - // ❌ Wrong: Unsupported type - liveMap.set('key', new Date()); - - // ✅ Correct: Use supported types - liveMap.set('key', Date.now()); // number - liveMap.set('data', { name: 'value' }); // object - ``` - - -5. **SDK-Specific Considerations** - - - **iOS/macOS**: Ensure correct type usage: - ```objc - // ❌ Wrong: Using NSString for base64 - [channel publish:@"event" data:stringData]; - - // ✅ Correct: Use NSData for binary - NSData *data = [stringData dataUsingEncoding:NSUTF8StringEncoding]; - [channel publish:@"event" data:data]; - ``` - - **Rust**: Ensure cipher block alignment: - ```rust - // Encrypted data must be block-aligned (16 bytes for AES) - assert!(encrypted_data.len() % 16 == 0); - ``` - -## Automatic Handling - -This is a client error that will not be automatically retried. The SDK cannot recover from invalid data types or encoding failures - you must fix the data format or configuration before the operation will succeed. - -## Known Production Issues - - - -### Idle Channel Encryption Issues -Some customers have experienced decryption failures after channels remain idle for extended periods. The issue typically resolves when reconnecting. If you encounter this: -- Monitor for patterns of idle period failures -- Consider implementing periodic keepalive messages -- Enable verbose logging to capture full context - -### Dynamic Channel Name Race Conditions -When using dynamically constructed channel names with encryption, race conditions can cause inconsistent encryption states. Always memoize channel names when using encryption. - -## Prevention - -- Always validate data types before publishing -- Use explicit JSON serialization for complex objects -- Maintain consistent cipher configuration across all clients -- Memoize channel names when using encryption to avoid race conditions -- Test encoding/decoding with your specific data types in development -- Enable verbose logging to capture full error context during debugging -- For production encrypted channels, implement monitoring for decryption failures - -## Related Errors - -• **[40000 - Bad Request](https://help.ably.io/error/40000)** - General bad request error that may occur alongside encoding issues - -• **[92001-92005 - Encryption Errors](https://help.ably.io/error/92001)** - Specific encryption configuration and cipher operation failures - -• **[80013 - Protocol Error](https://help.ably.io/error/80013)** - Protocol violations that may result from malformed encoded messages - -## Related Resources - -- [Message concepts documentation](https://ably.com/docs/messages/) -- [Encryption documentation](https://ably.com/docs/channels/options/encryption) -- [API Reference for Messages](https://ably.com/docs/api/rest-sdk/messages) -- [Channel options overview](https://ably.com/docs/channels/options) - -## Need Further Help? - -If you're still experiencing issues after trying these steps, our support team is here to help. - -**Contact Ably Support**: https://ably.com/support - -When contacting support, please provide: -- Your account ID and app ID -- The full error message including error code 40013 -- Steps to reproduce the issue -- Any relevant code snippets (without sensitive credentials) -- The SDK and version you're using -- Whether encryption is involved and if the issue occurs after idle periods - -Our team will help you resolve this issue as quickly as possible. - - - - - - - - - - - - - - - \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/92100-encoding-string-too-long.mdx b/src/pages/docs/platform/errors/codes/92100-encoding-string-too-long.mdx new file mode 100644 index 0000000000..dde18af0e8 --- /dev/null +++ b/src/pages/docs/platform/errors/codes/92100-encoding-string-too-long.mdx @@ -0,0 +1,132 @@ + + + + + + + + +# Error 92100: Encoding string too long + +## What Happened + +The message encoding metadata exceeded the 512-character limit in the Ruby SDK, preventing the message from being sent. + +## Quick Reference + +| Error Code | HTTP Status | Category | Retryable | Max Encoding Length | +|------------|-------------|----------|-----------|-------------------| +| 92100 | 400 | Client Error (Encoding) | No - requires fixing encoding chain | 512 characters | + +## Troubleshooting + +### Excessive Encoding Transformations +**Symptom**: "Encoding error, encoding value is too long" error when publishing messages +**Solution**: Reduce encoding transformations by letting the SDK handle encoding automatically + + +```ruby +# ✅ Correct: Let SDK handle encoding +channel = ably.channels.get('my-channel') +channel.publish('event', { data: 'value' }) + +# ❌ Avoid: Manual encoding chains +# Don't manually apply multiple encodings +``` + + +### Encryption Adding to Encoding Length +**Symptom**: Error occurs when using channel encryption with other encodings +**Solution**: Use channel cipher parameters instead of manual encryption encoding + + +```ruby +# Set encryption at channel level +channel_options = { cipher: { key: encryption_key } } +channel = ably.channels.get('secure-channel', channel_options) +channel.publish('event', data) # Encryption handled automatically +``` + + +### Accumulated Encoding Metadata +**Symptom**: Encoding string like `json/utf-8/base64/cipher+aes-256-cbc/gzip/base64` +**Solution**: Simplify your message pipeline - avoid redundant transformations + + +## Prevention + +- Design efficient message pipelines from the start +- Monitor encoding string length during development +- Use channel-level encryption configuration +- Trust the SDK's automatic encoding for objects + + +## Technical Details + +The Ruby SDK validates encoding string length before message transmission. Each transformation adds to the encoding metadata with '/' separators (e.g., `json/utf-8/base64`). When this accumulated string exceeds 512 characters, error 92100 is raised. + + +This limit is specific to the Ruby SDK implementation. Other Ably SDKs may not have this explicit restriction. + + +## Need Further Help? + +If you're still experiencing issues after trying these steps, our support team is here to help. + +**Contact Ably Support**: https://ably.com/support + +When contacting support, please provide: +- Your account ID and app ID +- The full error message including error code 92100 +- Steps to reproduce the issue +- Any relevant code snippets (without sensitive credentials) +- The SDK and version you're using + +Our team will help you resolve this issue as quickly as possible. + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/src/pages/docs/platform/errors/codes/92100-encoding-value-too-long.mdx b/src/pages/docs/platform/errors/codes/92100-encoding-value-too-long.mdx deleted file mode 100644 index 9329e46705..0000000000 --- a/src/pages/docs/platform/errors/codes/92100-encoding-value-too-long.mdx +++ /dev/null @@ -1,191 +0,0 @@ - - - - - - - - -# Error 92100: Encoding value too long - -## What Happened - -The message encoding metadata string exceeded the maximum allowed length of 512 characters. - -## Quick Reference - -| Error Code | HTTP Status | Category | Retryable | -|------------|-------------|----------|-----------| -| 92100 | 400 | Client Error (Encoding) | No - requires fixing message encoding | - -## Quick Fix - -- Reduce the number of encoding transformations applied to your message -- Avoid encoding already-encoded data -- Use only essential encoding steps for your use case - -## Error Messages - -You may see this message: -- "Encoding error, encoding value is too long: '{encoding}'" - -The `{encoding}` shows the actual encoding string that exceeded the limit. - -## Common Causes - -1. **Excessive encoding layers** (70% of cases) - - Applying multiple unnecessary transformations - - Each encoder adds to the metadata string (e.g., `json/utf-8/base64/cipher+aes-256-cbc/gzip`) - - The encoding chain grows with each transformation applied - - -2. **Recursive encoding** (20% of cases) - - Encoding already-encoded messages - - Double-encoding JSON data - - Processing the same message through encoders multiple times - - -3. **Unnecessary transformations** (10% of cases) - - Including redundant base64 encoding - - Multiple compression layers - - Using both encryption and encoding when only one is needed - - -## Resolution Steps - -1. **Review your encoding chain** - - Check which encodings are being applied to your messages - - The encoding string concatenates all transformations with '/' separator - - Example problematic chain: `json/utf-8/base64/cipher+aes-256-cbc/gzip/base64` - - -2. **Reduce encoding layers** - - Use only the essential encodings for your use case - - Avoid encoding data that's already in the correct format - - Choose either compression or encryption, not necessarily both - - -3. **Optimize your message structure** - - Apply compression before encryption if using both - - Use efficient serialization formats - - Consider sending raw data when appropriate - - -4. **Monitor encoding chain length** - - Keep track of the encoding metadata string length - - Remember the 512 character limit includes all transformation identifiers - - Test with production-like data to catch issues early - - -## Automatic Handling - -This is a client-side validation error that occurs before the message is sent to Ably servers. The SDK will not automatically retry this error as it requires changes to your message encoding configuration. - - -## Prevention - -- Use minimal necessary encodings for your messages -- Avoid double-encoding data (e.g., JSON-encoding already-JSON data) -- Choose the most efficient transformation order -- Document your encoding requirements to prevent unnecessary additions -- Regularly review and optimize your encoding pipeline - - -## Performance Impact - -Long encoding chains impact your application by: -- Slowing message processing -- Increasing message size and bandwidth usage -- Adding latency to publish and subscribe operations -- Consuming more CPU for encoding/decoding - - -## Related Errors - -• **[92001 - Encoding Error](https://help.ably.io/error/92001)** - General encoding failures during message transformation - -• **[92005 - Decoding Error](https://help.ably.io/error/92005)** - Issues when attempting to decode received messages - -## Related Resources - -- [Message concepts documentation](https://ably.com/docs/messages/) -- [Encryption documentation](https://ably.com/docs/channels/options/encryption) -- [API Reference - Messages](https://ably.com/docs/api/rest-sdk/messages) - -## Need Further Help? - -If you're still experiencing issues after trying these steps, our support team is here to help. - -**Contact Ably Support**: https://ably.com/support - -When contacting support, please provide: -- Your account ID and app ID -- The full error message including error code 92100 -- Steps to reproduce the issue -- Any relevant code snippets (without sensitive credentials) -- The SDK and version you're using - -Our team will help you resolve this issue as quickly as possible. - - - - - - - - - - - - - - - - - \ No newline at end of file