API Troubleshooting

Common Errors

400 Bad Request

{
  "error": "bad_request",
  "message": "Invalid request parameters"
}

Causes:

• Missing required fields
• Invalid JSON format
• Invalid parameter values
• Wrong data type

Solution:

# Verify request format
curl -X POST https://api.solatis.team/v1/documents \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "url": "https://example.com/doc.pdf",
    "metadata": {"source": "email"}
  }'

401 Unauthorized

{
  "error": "unauthorized",
  "message": "Invalid or missing API key"
}

Solutions:

• Verify API key in header
• Check key hasn't been deleted
• Regenerate if unsure
• Use correct format: Authorization: Bearer KEY

403 Forbidden

{
  "error": "forbidden",
  "message": "Insufficient permissions"
}

Solutions:

• Check API key scopes
• Verify organization access
• Request higher permissions

404 Not Found

{
  "error": "not_found",
  "message": "Document doc123 not found"
}

Solutions:

• Verify document ID is correct
• Check if document was deleted
• Ensure you have access

429 Rate Limited

{
  "error": "rate_limited",
  "message": "Too many requests",
  "retry_after": 120
}

Solution:

import time

def make_request_with_backoff(url, headers):
    for attempt in range(3):
        try:
            response = requests.get(url, headers=headers)
            if response.status_code == 429:
                wait_time = int(response.headers.get('Retry-After', 60))
                print(f"Rate limited. Waiting {wait_time}s...")
                time.sleep(wait_time)
                continue
            return response
        except Exception as e:
            if attempt < 2:
                time.sleep(2 ** attempt)

500 Server Error

{
  "error": "server_error",
  "message": "Internal server error"
}

Solutions:

• Retry after 5 seconds
• Check status page: https://status.solatis.team
• Contact support if persistent

Debugging Tips

Enable Request Logging

Python:

import logging
import http.client

http.client.HTTPConnection.debuglevel = 1

logging.basicConfig()
logging.getLogger().setLevel(logging.DEBUG)

# Now make requests
response = requests.get(...)

Log Request Details

import requests

response = requests.get(
    "https://api.solatis.team/v1/documents",
    headers={"Authorization": f"Bearer {api_key}"}
)

print(f"Status: {response.status_code}")
print(f"Headers: {response.headers}")
print(f"Body: {response.text}")

Use Curl with Verbose

curl -v \
  -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.solatis.team/v1/documents

Performance Issues

Slow Requests

Check:

• Network latency
• API key rate limits
• Batch size (reduce if too large)
• Document processing time

Optimize:

# Use batch operations
batch_upload(api_key, [doc1, doc2, doc3])  # 1 request

# Not
upload(api_key, doc1)  # 3 requests
upload(api_key, doc2)
upload(api_key, doc3)

High Latency

• Use regional API endpoints if available
• Implement connection pooling
• Cache results locally
• Use async requests

Authentication Issues

Expired Token

{
  "error": "token_expired",
  "message": "OAuth token has expired"
}

Solution:

# Refresh token
response = requests.post(
    "https://api.solatis.team/oauth/token",
    data={
        "grant_type": "refresh_token",
        "refresh_token": refresh_token,
        "client_id": client_id,
        "client_secret": client_secret
    }
)

new_token = response.json()['access_token']

Invalid Scope

{
  "error": "insufficient_scope",
  "message": "This operation requires 'documents:write' scope"
}

Solution:

• Generate new API key with required scopes
• Or use OAuth with broader scopes

Data Issues

File Too Large

{
  "error": "file_too_large",
  "message": "Maximum file size is 100MB"
}

Solution:

• Split document before uploading
• Compress document
• Request increase from support

Unsupported Format

{
  "error": "unsupported_format",
  "message": "Format .xyz not supported"
}

Supported Formats:

• PDF, DOCX, XLSX, PPTX
• TXT, MD
• JPG, PNG, GIF
• ZIP (auto-extracted)

Analysis Failed

{
  "error": "analysis_failed",
  "message": "Could not analyze document"
}

Debugging:

# Get error details
batch = get_batch_status(api_key, batch_id)
for doc in batch['documents']:
    if doc['status'] == 'failed':
        print(f"Error: {doc.get('error')}")
        print(f"Details: {doc.get('error_details')}")

Connectivity Issues

Connection Refused

Error: Connection refused

Check:

• API endpoint URL is correct
• Network connectivity
• Firewall rules
• VPN if needed

Timeout

# Set timeout for requests
response = requests.get(
    url,
    headers=headers,
    timeout=30  # 30 second timeout
)

SSL Certificate Error

SSL: CERTIFICATE_VERIFY_FAILED

Solution (not recommended for production):

# Disable SSL verification only for debugging
response = requests.get(url, verify=False)

Better: Fix root cause

• Update SSL certificates
• Check system clock
• Update requests library

Batch Issues

Batch Processing Slow

• Monitor via webhooks instead of polling
• Increase polling interval
• Check status page for system load

Batch Expired

{
  "error": "batch_expired",
  "message": "Results expire after 7 days"
}

• Retrieve results within 7 days
• Store batch ID for reference
• Archive important batches

Getting Help

Check Logs

# API usually includes request ID
response = requests.get(...)
request_id = response.headers.get('X-Request-ID')
print(f"Request ID: {request_id}")

Contact Support

When reporting issues, provide:

• Request ID
• Timestamp of issue
• API key (masked)
• Error message (full JSON)
• Steps to reproduce

Email: api-support@solatis.team

Status Page

Check https://status.solatis.team for:

• Planned maintenance
• Service incidents
• Performance reports

Best Practices

1. Always include error handling

   try:
       response = requests.get(url, headers=headers)
       response.raise_for_status()
   except requests.exceptions.RequestException as e:
       print(f"Error: {e}")

2. Implement retry logic

   max_retries = 3
   for attempt in range(max_retries):
       try:
           return make_request()
       except Exception as e:
           if attempt < max_retries - 1:
               time.sleep(2 ** attempt)

3. Monitor rate limits

   remaining = response.headers.get('X-Rate-Limit-Remaining')
   print(f"Requests remaining: {remaining}")

4. Test in staging first

   • Use staging environment
   • Test error scenarios
   • Verify retry logic
   • Load test if needed

5. Log important details

   • Request ID
   • Timestamp
   • Error message
   • Context information