Initial set of auto-generated error pages for review and to kickstart the iterative improvement cycle

src/pages/docs/platform/errors/codes/0-generic-client-error.mdx

@@ -0,0 +1,238 @@
+<!-- Generated by: ably-os errors document-error-codes -->
+<!-- Repository: https://github.com/ably/ably-os -->
+<!-- Command: ./bin/ably-os errors document-error-codes 0 -->
+<!-- Generated: 2025-08-24T21-13-57-640Z -->
+<!-- Sources: 
+     - Analysis: https://github.com/ably/ably-os/blob/5f4ba43/output/error-codes/research/0-analysis.md
+     - Knowledge: https://github.com/ably/ably-os/blob/5f4ba43/output/error-codes/research/0-knowledge.md
+     - Editorial notes: https://github.com/ably/ably-os/blob/5f4ba43/src/prompts/errors/editorial-notes.md
+-->
+<!-- Key Approach: Enhance existing documentation with better structure, related errors section, and verified content while preserving valuable insights -->
+<!-- Citations: Complete source attribution with line numbers available at bottom of document -->
+
+# 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
+- "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
+
+<!-- Source: Analysis from https://github.com/ably/ably-os/blob/5f4ba43/output/error-codes/research/0-analysis.md lines 21-117 -->
+
+## 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
+   <!-- Source: Analysis finding from https://github.com/ably/ably-os/blob/5f4ba43/output/error-codes/research/0-analysis.md lines 161-165 -->
+
+2. **Network connectivity issues** (23% of cases)
+   - No internet connection detected
+   - Connection timeout during initialization
+   - Connection closed unexpectedly
+   <!-- Source: Analysis finding from https://github.com/ably/ably-os/blob/5f4ba43/output/error-codes/research/0-analysis.md lines 167-172 -->
+
+3. **Invalid data types or encoding** (18% of cases)
+   - Data type not supported for encoding
+   - Encryption or Base64 encoding failure
+   - Unsupported data format provided
+   <!-- Source: Analysis finding from https://github.com/ably/ably-os/blob/5f4ba43/output/error-codes/research/0-analysis.md lines 179-184 -->
+
+4. **Generic SDK errors** (14% of cases)
+   - Exception conversion to error format
+   - Unknown error conditions
+   - Fallback when no specific code available
+   <!-- Source: Analysis finding from https://github.com/ably/ably-os/blob/5f4ba43/output/error-codes/research/0-analysis.md lines 174-178 -->
+
+## 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
+   <!-- Source: Based on analysis showing message importance from https://github.com/ably/ably-os/blob/5f4ba43/output/error-codes/research/0-analysis.md line 217 -->
+
+2. **For missing parameter errors**
+   - Review the SDK documentation for required parameters
+   - Ensure all mandatory fields are provided
+   - Check parameter types match expectations
+   <!-- Source: Analysis pattern from https://github.com/ably/ably-os/blob/5f4ba43/output/error-codes/research/0-analysis.md lines 161-165 -->
+
+3. **For network connectivity issues**
+   - Verify internet connection is available
+   - Check firewall or proxy settings
+   - Ensure the Ably service endpoints are accessible
+   <!-- Source: Analysis pattern from https://github.com/ably/ably-os/blob/5f4ba43/output/error-codes/research/0-analysis.md lines 62-64 -->
+
+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
+   <!-- Source: Analysis pattern from https://github.com/ably/ably-os/blob/5f4ba43/output/error-codes/research/0-analysis.md lines 69-86 -->
+
+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
+   <!-- Source: Knowledge recommendation from https://github.com/ably/ably-os/blob/5f4ba43/output/error-codes/research/0-knowledge.md lines 59-60 -->
+
+## 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
+<!-- Source: Analysis showing client-side validation pattern from https://github.com/ably/ably-os/blob/5f4ba43/output/error-codes/research/0-analysis.md line 213 -->
+
+## 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
+<!-- Source: Analysis from https://github.com/ably/ably-os/blob/5f4ba43/output/error-codes/research/0-analysis.md lines 187-193 -->
+
+### Rust (ably-rust)
+Uses `ErrorCode::NotSet` variant:
+- Default when no specific error code provided
+- Fallback for unmappable HTTP status codes
+<!-- Source: Analysis from https://github.com/ably/ably-os/blob/5f4ba43/output/error-codes/research/0-analysis.md lines 195-200 -->
+
+### Swift Asset Tracking
+Connection lifecycle errors:
+- Connection timeout during startup
+- Connection closed during initialization
+<!-- Source: Analysis from https://github.com/ably/ably-os/blob/5f4ba43/output/error-codes/research/0-analysis.md lines 202-206 -->
+
+## 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.
+<!-- Source: Analysis observations from https://github.com/ably/ably-os/blob/5f4ba43/output/error-codes/research/0-analysis.md lines 209-221 -->
+
+## 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)
+
+## 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.
+
+**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.
+
+<!-- =============================================== -->
+<!-- INTERNAL DOCUMENTATION (NOT RENDERED) -->
+<!-- =============================================== -->
+
+<!-- SOURCES USED (ALWAYS use GitHub URLs with current SHA, never local paths):
+- Analysis File: https://github.com/ably/ably-os/blob/5f4ba43/output/error-codes/research/0-analysis.md
+- Knowledge File: https://github.com/ably/ably-os/blob/5f4ba43/output/error-codes/research/0-knowledge.md
+- Editorial Notes: https://github.com/ably/ably-os/blob/5f4ba43/src/prompts/errors/editorial-notes.md (No specific error-specific notes for 0)
+- Existing Documentation: https://github.com/ably/docs/blob/main/src/pages/docs/platform/errors/codes/0-generic-client-error.mdx (enhanced existing documentation)
+- Repository Overviews: Not consulted as research files contained comprehensive information
+-->
+
+<!-- CONTENT DECISIONS:
+- FAQ Content Preserved: No specific FAQ content found for error code 0 in knowledge file
+- Content Excluded: Internal implementation details that wouldn't help customers
+- Recommendations Source: Based on patterns identified in analysis file showing common causes and resolutions
+- Code Examples Rationale: No code examples included as this is a generic error requiring context-specific resolution
+-->
+
+<!-- ATTRIBUTION BY SECTION:
+- Common Causes: 
+  - Cause 1 (Missing parameters): Based on analysis findings in https://github.com/ably/ably-os/blob/5f4ba43/output/error-codes/research/0-analysis.md lines 161-165
+  - Cause 2 (Network issues): From analysis at https://github.com/ably/ably-os/blob/5f4ba43/output/error-codes/research/0-analysis.md lines 167-172
+  - Cause 3 (Invalid data): From SDK code patterns at https://github.com/ably/ably-os/blob/5f4ba43/output/error-codes/research/0-analysis.md lines 179-184
+  - Cause 4 (Generic errors): From analysis at https://github.com/ably/ably-os/blob/5f4ba43/output/error-codes/research/0-analysis.md lines 174-178
+- Resolution Steps:
+  - Step 1: Source from analysis showing message importance at https://github.com/ably/ably-os/blob/5f4ba43/output/error-codes/research/0-analysis.md line 217
+  - Step 2: Based on parameter validation pattern from analysis lines 161-165
+  - Step 3: Network issues from analysis lines 62-64
+  - Step 4: Data type validation from analysis lines 69-86
+  - Step 5: Logging recommendation from knowledge file lines 59-60
+- Prevention: Based on client-side validation pattern from analysis line 213
+- SDK-Specific Behavior: All from analysis lines 187-206
+- Important Notes: From analysis observations lines 209-221
+-->
+
+<!-- URL Validation Completed: 2025-08-24T21-13-57-640Z -->
+<!-- External URLs verified: 4 | Corrected: 0 | Exempted internal: 2 -->
+
+<!-- DOCUMENTATION SHORTCOMINGS:
+⚠️ Areas where Ably documentation could be improved:
+- Missing: Official documentation for error code 0 as it's not in the protocol specification
+- Impact: Developers encounter this error but have no official reference
+- Recommendation: Consider standardizing error codes across SDKs to avoid generic code 0
+- Severity: Medium - affects debugging experience but not critical functionality
+-->
+
+<!-- IMPROVEMENT INSTRUCTIONS:
+To improve this error code documentation:
+1. First approach: Update editorial-notes.md in ably-os repository with specific guidance for error 0
+2. Regenerate: Run `./bin/ably-os errors document-error-codes 0 --force`
+3. For broader improvements: Review and update ably-os prompt templates
+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
+-->