trustcafe-api-wrapper/docs/TROUBLESHOOTING.md

Troubleshooting Guide

Common issues and solutions when using the TrustCafé API wrapper.

Table of Contents

• Authentication Issues
• Connection Issues
• Token Management Issues
• API Call Issues
• Environment Issues
• Data Handling Issues
• Performance Issues
• Debugging Strategies

Authentication Issues

Issue: "Invalid client credentials"

Symptoms:

ValueError: Client credentials invalid

Causes:

• Incorrect client_id or client_secret
• Using alpha credentials on production environment (or vice versa)
• Credentials haven't been saved yet from the TrustCafé admin panel

Solutions:

1. Verify credentials from the admin panel

2. Ensure environment matches credentials:

   # Check your credentials are for the right environment
   print(f"Environment: {env}")  # Should match where credentials were created
   

3. Generate new credentials if needed:

   • Visit: https://www.trustcafe.io/en/myaccount/apiaccess
   • Click "Create new client credentials key pair"
   • Save the new credentials

4. Verify credentials aren't expired (trustcafe-side expiration)

---

Issue: "Token expired"

Symptoms:

Exception: Token has expired

Causes:

• Access token duration has expired (~3 months from creation)
• Time mismatch between systems

Solutions:

1. Automatically refresh token:

   # Check token validity and refresh if needed
   if not API.is_token_valid():
       API.handle_token()
   

2. Pre-load tokens before long operations:

   # Ensure token is fresh before making many requests
   API.handle_token()
   
   # Now all API calls will succeed
   

3. Provide longer expiration time for testing:

   # Manual token with long expiration
   API.set_token({
       "access_token": "your-token",
       "access_token_timeout": 9999999999  # Far future date
   })
   

---

Issue: "Permission denied" when making requests

Symptoms:

ForbiddenError: Insufficient permissions for this API endpoint

Causes:

• Client credentials lack required scopes
• Not authenticated (no access token)

Solutions:

1. Verify scopes on the admin panel
2. Ensure authentication is enabled in all requests:

   # Make sure to authenticate
   response = API.make_request(
       "GET",
       "content",
       "some/path",
       authenticate=True  # Ensure this is True
   )
   
   # For guest requests (if allowed)
   response = API.make_request(
       "GET",
       "content",
       "some/path",
       authenticate=False
   )
   

---

Connection Issues

Issue: "No internet connection" or "Connection refused"

Symptoms:

ConnectionError: An error occurred while making the request

Causes:

• Network connectivity issues
• Firewall blocking requests
• API service unavailable

Solutions:

1. Check network connectivity:

   # Test connectivity to alpha/production endpoints
   ping alpha.wts2.net
   ping trustcafe.io
   

2. Verify firewall rules allow HTTPS requests

3. Try alternative network (mobile hotspot vs. Wi-Fi)

4. Check if TrustCafé services are up:

   • Production: https://trustcafe.io
   • Alpha: https://alpha.wts2.net

5. Add retry logic:

   import time
   
   def retry_request(request_func, max_retries=3):
       for attempt in range(max_retries):
           try:
               return request_func()
           except ConnectionError as e:
               if attempt < max_retries - 1:
                   time.sleep(1)
               else:
                   raise
   

---

Issue: "DNS resolution failed"

Symptoms:

requests.exceptions.ConnectionError: DNS resolution failed

Causes:

• DNS server issues
• VPN interfering with DNS
• Incorrect hostname

Solutions:

1. Check DNS:

   nslookup alpha.wts2.net
   nslookup trustcafe.io
   

2. Try changing DNS server:

   # Use Google DNS (8.8.8.8, 8.8.4.4)
   # Or Cloudflare (1.1.1.1, 1.0.0.1)
   

3. Disable VPN temporarily

4. Check configuration for correct hostnames (alpha.wts2.net vs trustcafe.io)

---

Token Management Issues

Issue: "Token file not found"

Symptoms:

FileNotFoundError: Token data file 'token_data_alpha.json' not found

Causes:

• First-time run
• Token directory not created
• Wrong path specified

Solutions:

1. API <environment>_handle_token automatically creates file on first use

2. Ensure working directory is writable

3. Specify custom token file path:

   API.handle_token(token_data_path="my/custom/path/token_data.json")
   

4. Manually create token file:

   token_data = API.sign_in()
   with open("token_data_alpha.json", "w") as f:
       json.dump(token_data, f)
   

---

Issue: "Permission denied: cannot write token file"

Symptoms:

PermissionError: [Errno 13] Permission denied: 'token_data_alpha.json'

Causes:

• Working directory not writable
• File locked by another process
• Insufficient permissions

Solutions:

1. Ensure writable directory:

   import os
   
   # Use a writable directory
   writable_dir = os.path.expanduser("~")  # Home directory
   API.handle_token(token_data_path=f"{writable_dir}/tokens/token_data.json")
   

2. Check file permissions:

   ls -la token_data_alpha.json
   chmod 644 token_data_alpha.json
   

3. Try with a custom directory:

   import tempfile
   
   # Use temp directory
   with tempfile.TemporaryDirectory() as tmpdir:
       API.handle_token(token_data_path=f"{tmpdir}/token_data.json")
   

---

Issue: "Token file corrupted"

Symptoms:

json.decoder.JSONDecodeError: Expecting value: line 1 column 1 (char 0)

Causes:

• File corruption during write
• File truncated by other process

Solutions:

1. Delete corrupted token file:

   rm token_data_alpha.json
   

2. Let wrapper recreate it

3. Check for concurrent token writes:

   from threading import Lock
   
   token_lock = Lock()
   
   def safe_handle_token():
       with token_lock:
           API.handle_token()
   

---

API Call Issues

Issue: "400 Bad Request" or "Invalid parameter"

Symptoms:

ValueError: Invalid parameter or data format
400 Bad Request

Causes:

• Missing required parameters
• Incorrect parameter format
• Parameter validation failure

Solutions:

1. Check parameter requirements in API Reference:

   • See API Reference for each job

2. Verify parameter types:

   # Use correct types
   API.run_job('post.create', {
       "postText": "text string",  # Should be string
       "blurLabel": None,          # None is okay
       # Wrong: "blurLabel": ""  (empty string)
   })
   

3. Verify required parameters:

   # Example for post.create
   required_fields = ['postText', 'parent']
   
   if 'parent' not in data:
       raise ValueError("Required field 'parent' is missing")
   

4. Use debug mode to see request:

   API = APIClient(debug=True)
   
   # Now you'll see the exact data being sent
   API.run_job('post.create', data)
   

---

Issue: "404 Not Found"

Symptoms:

FileNotFoundError: Endpoint not found
404 Not Found

Causes:

• Wrong endpoint or path
• Resource doesn't exist
• Branch/post not found

Solutions:

1. Verify the path is correct

2. Check if resource exists:

   # Verify branch exists
   branch = API.run_job('branch.get', "branch-name")
   
   if not branch:
       print("Branch does not exist")
   
   # Verify post exists
   post = API.run_job('post.get', "post-id")
   
   if not post:
       print("Post does not exist")
   

3. Check for spelling mistakes in paths

4. Use debug mode to see exact path being sent:

   API = APIClient(debug=True)
   API.run_job('post.create', data)  # See exact request path
   

---

Issue: "500 Internal Server Error"

Symptoms:

ConnectionError: An error occurred
500 Internal Server Error

Causes:

• TrustCafé server error
• Database issues on server side
• Unhandled edge case

Solutions:

1. Wait a moment and retry
2. Check TrustCafé status
3. Try at a different time
4. Consider this transient error:

   import time
   
   def retry_server_error(func, max_retries=3):
       for attempt in range(max_retries):
           try:
               return func()
           except ConnectionError as e:
               if str(e).find("500") != -1:
                   if attempt < max_retries - 1:
                       time.sleep(2 ** attempt)  # Exponential backoff
               else:
                   raise
   

---

Issue: "Rate limit exceeded"

Symptoms:

429 Too Many Requests

Causes:

• Too many API calls too quickly
• Gratuitous API usage

Solutions:

1. Implement rate limiting (see main README for example)

2. Space out your API calls:

   import time
   
   def spaced_request(request_func, delay=1):
       result = request_func()
       if hasattr(request_func, 'call_count'):
           request_func.call_count += 1
           if request_func.call_count > 30:
               time.sleep(2)
       return result
   

3. Use pagination for large result sets

4. Consider caching results when possible

---

Environment Issues

Issue: "Environment 'invalid' is not valid"

Symptoms:

ValueError: Environment 'staging' is not valid. Must be one of: ['alpha', 'production']

Causes:

• Typo in environment name
• Passing only environment once
• Environment changed incorrectly

Solutions:

1. Use correct environment names:

   • "alpha" (development/staging)
   • "production" (live)

2. Avoid modifying environment mid-session after API init

3. Reinitialize if you need to switch:

   # Create new API client for new environment
   API_prod = APIClient(
       client_id="prod-id",
       client_secret="prod-secret",
       env="production"
   )
   
   # Old API still has old environment
   print(API.environment)  # "alpha"
   

---

Issue: "Endpoint 'invalid' is not defined"

Symptoms:

ValueError: Endpoint 'noservices' is not defined in the API client.

Causes:

• Typo in endpoint name
• Custom endpoint not configured
• Server-side endpoint changed

Solutions:

1. Check available endpoints in APIClient code
2. Use correct endpoints: "content", "auth", "audrey", etc.
3. Review documentation for correct API structure

---

Data Handling Issues

Issue: "JSON decode error" or "Response is not valid JSON"

Symptoms:

ValueError: Response is not valid JSON: Expecting value: line 1 column 1 (char 0)

Causes:

• Server returning non-JSON response
• Network error causing incomplete response
• Empty response

Solutions:

1. Add error handling:

   try:
       response = API.make_request("GET", "content", "path")
       response_json = response.json()
   except json.JSONDecodeError as e:
       print(f"Failed to parse JSON: {e}")
       print(f"Response was: {response}")
   

2. Check if server is responding correctly

3. Verify network connectivity

4. Check for errors in response:

   if 'error' in response:
       raise Exception(f"API Error: {response['error']}")
   

---

Issue: Empty response or missing data

Symptoms:

expected to find Items in response, but didn't

Causes:

• Query returns no results
• Pagination not handled
• Response structure misunderstanding

Solutions:

1. Check for empty results:

   response = API.make_request("GET", "content", "some/path")
   
   if 'Items' not in response or not response.get('Items'):
       print("No results found")
   

2. Check pagination status:

   if 'LastEvaluatedKey' in response:
       print("More results available, need pagination")
   

3. Verify response structure understanding

---

Performance Issues

Issue: "Timeout" errors

Symptoms:

requests.exceptions.Timeout: Request timed out

Causes:

• Network slowness
• Large result sets
• Slow server response

Solutions:

1. Increase timeout:

   # Unfortunately, current implementation doesn't expose timeout
   # This would need updating in apiclient.py
   
   # If you control code, you can modify the make_request method
   # to accept a timeout parameter
   

2. Reduce request complexity

3. Implement pagination for large datasets

4. Use async if available

---

Issue: Slow token refresh

Symptoms:

• Initial request slow
• Token refresh takes too long

Causes:

• Network latency to auth endpoint
• Server-side delays

Solutions:

1. Pre-load token:

   # Get token before doing anything time-sensitive
   API.handle_token()
   
   # All subsequent calls will use cached token
   

2. Use manual token for frequent operations:

   API.set_token({
       "access_token": token,
       "access_token_timeout": 9999999999
   })
   

---

Debugging Strategies

Enable Debug Mode

API = APIClient(
    client_id="your-id",
    client_secret="your-secret",
    env="alpha",
    debug=True  # Enables verbose logging
)

This will print:

• Request method
• Full URL
• Headers
• Request payload

Add Logging

import logging

logging.basicConfig(level=logging.DEBUG)

logger = logging.getLogger(__name__)

try:
    result = API.run_job('post.create', data)
    logger.debug(f"Success: {result}")
except Exception as e:
    logger.error(f"Failed: {e}", exc_info=True)

Verify Request Flow

def trace_request(func, *args, **kwargs):
    """Trace each request"""
    import inspect

    # Get function name
    func_name = inspect.getmember(BuiltinFunctionType, func).__name__

    print(f"Calling: {func_name}")
    print(f"Args: {args}")
    print(f"Kwargs: {kwargs}")

    result = func(*args, **kwargs)

    print(f"Result: {result}")
    return result

Network Inspection

import requests

# Direct inspection of requests
import logging
requests_log = logging.getLogger("urllib3")
requests_log.setLevel(logging.DEBUG)

requests_log.propagate = True

---

Getting Help

If you've tried all of the above and still have issues:

1. Check the Code: Review the latest version on Forgejo

   • Forgejo Repository

2. Check TrustCafé Status: Verify services are up

   • Production
   • Alpha

3. Review Contributions: Check for known issues

   • Open an issue on GitLab
   • Check if a fix is already in progress

4. Contact Support: For resolved but unreleased issues

   • WikiTribune team
   • Build Product Slack/Discord

---

Quick Reference

Common error codes:

• 400 Bad Request: Invalid parameters (check API Reference)
• 401 Unauthorized: Invalid/missing token (call handle_token())
• 403 Forbidden: Insufficient permissions (check scopes)
• 404 Not Found: Wrong path or resource doesn't exist
• 429 Too Many Requests: Rate limit exceeded (apply rate limiting)
• 500 Internal Server Error: Service error (wait and retry)
• Timeout: Network issues (check connectivity)

---

Remember: Most issues are easily solved with proper error handling, verification of credentials, and rate limiting.