Troubleshooting

SSL/TLS Issues

Error: "SSL: CERTIFICATE_VERIFY_FAILED"

Symptom: Certificate verification fails during HTTPS connection.

Causes:

• CA certificate not added to trust store
• Invalid or expired CA certificate
• Certificate mismatch

Solutions:

1. Verify CA certificate is loaded:

# Python
session.verify = 'ca.pem'

2. Check certificate validity:

openssl x509 -in ca.pem -noout -dates

3. Inspect certificate chain:

openssl s_client -connect 47.236.197.241:6088 -showcerts

Error: "SSL Handshake Failed" / "SNI Error"

Symptom: Connection fails during TLS handshake.

Cause: SNI (Server Name Indication) not set to loulilouwai.net.

Solution:

Always set SNI to loulilouwai.net even when connecting to an IP address.

Python:

class SNIAdapter(HTTPAdapter):
    def init_poolmanager(self, *args, **kwargs):
        kwargs['server_hostname'] = 'loulilouwai.net'
        return super().init_poolmanager(*args, **kwargs)

session.mount('https://', SNIAdapter())

cURL:

curl --resolve loulilouwai.net:6088:47.236.197.241 \
     --cert client.crt --key client.key --cacert ca.crt \
     https://loulilouwai.net:6088/api/v1/system/login

Node.js:

const agent = new https.Agent({
  servername: 'loulilouwai.net'  // Critical!
});

Error: "Client Certificate Required"

Symptom: Server rejects connection requiring client certificate.

Cause: Client certificate not provided in TLS handshake.

Solution: Ensure both certificate AND private key are configured:

Python:

session.cert = ('client.pem', 'key.pem')  # Both required

cURL:

curl --cert client.crt --key client.key  # Both flags needed

Authentication Errors

HTTP 403 Forbidden

Symptom: API returns 403 status code.

Causes:

1. Token expired
2. Certificate not sent with request
3. Invalid token

Solutions:

1. Token Expiration (Most Common)

Refresh your token using certificate login:

def refresh_token():
    login_url = f"{BASE_URL}/system/login"
    payload = {"name": UUID, "password": ""}  # Empty password!
    response = session.post(login_url, json=payload)
    return response.json()['auth_token']

# Auto-refresh wrapper
def api_call_with_retry(method, url, **kwargs):
    response = session.request(method, url, **kwargs)
    
    if response.status_code == 403:
        # Refresh and retry
        new_token = refresh_token()
        kwargs.setdefault('headers', {})['X-Molly-Wallet-Token'] = new_token
        response = session.request(method, url, **kwargs)
    
    return response

2. Certificate Not Sent

Verify certificate is configured:

print(session.cert)  # Should show: ('client.pem', 'key.pem')

3. Wrong Header Format

❌ Incorrect:

headers = {'Authorization': 'Bearer ' + token}  # NOT SUPPORTED

✅ Correct:

headers = {'X-Molly-Wallet-Token': token}

HTTP 401 Unauthorized

Symptom: Password-based login fails.

Causes:

• Incorrect UUID or api_key
• Typo in credentials

Solution:

1. Verify credentials are correct
2. Check for extra whitespace or newlines
3. Ensure you're using the correct namespace UUID

Connection Issues

Error: "Connection Refused" / "Connection Timeout"

Symptom: Cannot connect to API server.

Causes:

• Firewall blocking outbound connections
• Network issues
• Wrong API URL
• Server unavailable

Debugging Steps:

1. Test basic connectivity:

ping 47.236.197.241

2. Test port reachability:

telnet 47.236.197.241 6088
# or
nc -zv 47.236.197.241 6088

3. Check firewall rules:

# Linux
sudo iptables -L -n

# Windows
netsh advfirewall firewall show rule name=all

4. Test with cURL:

curl -v https://47.236.197.241:6088/api/v1/system/login --insecure

Certificate Issues

Error: "Permission Denied" when loading private key

Symptom: Application cannot read key.pem.

Cause: Incorrect file permissions.

Solution:

# Unix/Linux/Mac
chmod 600 key.pem
chown $USER key.pem

# Verify
ls -la key.pem
# Should show: -rw------- (600)

Error: "Invalid Certificate Format"

Symptom: Cannot parse certificate or key.

Causes:

• File corrupted during save
• Wrong encoding
• Extra characters added

Solution:

1. Verify PEM format:

openssl x509 -in client.pem -text -noout
openssl rsa -in key.pem -check

2. Check for extra whitespace: Ensure certificates start with -----BEGIN CERTIFICATE----- and end with -----END CERTIFICATE----- with no extra spaces.

Debugging Tools

Enable Debug Logging

Python:

import logging
import http.client as http_client

http_client.HTTPConnection.debuglevel = 1
logging.basicConfig(level=logging.DEBUG)

Node.js:

process.env.NODE_TLS_REJECT_UNAUTHORIZED = '0';  // For testing only!
process.env.NODE_DEBUG = 'tls,http';

cURL:

curl -v  # Verbose mode
curl --trace-ascii debug.txt  # Full trace

Inspect TLS Handshake

openssl s_client -connect 47.236.197.241:6088 \
                  -cert client.pem -key key.pem \
                  -CAfile ca.pem \
                  -servername loulilouwai.net

Verify Certificate Chain

openssl verify -CAfile ca.pem client.pem

Common Mistakes Checklist

• Forgot to set SNI to loulilouwai.net
• Used Authorization: Bearer instead of X-Molly-Wallet-Token
• Certificate not provided with request
• Didn't refresh token after 403
• Re-ran password flow instead of certificate login after 403
• Lost api_key (must recreate namespace)
• File permissions too open on private key
• CA certificate not in trust store

Still Stuck?

If you're still experiencing issues:

1. Check the logs - Enable debug logging to see the full request/response
2. Verify setup - Go through the Quick Start Guide again
3. Test with cURL - Isolate whether the issue is in your code or configuration
4. Review code examples - Compare with working Code Examples

Next Steps

• Quick Start Guide
• Authentication Details
• Code Examples