Skip to main content

​
Quick Troubleshooting Checklist

Before diving into specific issues, verify these basics:
  • ✅ Your API key is valid and not expired
  • ✅ You’re using the correct base URL: https://api.upwell.com
  • ✅ All required headers are included
  • ✅ Request format follows the API specification
  • ✅ You have sufficient permissions for the operation

​
Common Issues and Solutions

​
Authentication Problems

Symptoms: Getting 401 Unauthorized errorsSolutions:
  1. Verify API Key Format 
    # Correct format
curl -H "Authorization: upw_live_1234567890abcdef" https://api.upwell.com/api/rest/invoices
  2. Check Key Expiration
    • Log into your Upwell dashboard
    • Navigate to Settings → API Keys
    • Verify your key’s expiration date
  3. Regenerate API Key
    • Generate a new API key if the current one is expired
    • Update your application with the new key
    • Revoke the old key for security
Symptoms: Getting 403 Forbidden errorsSolutions:
  1. Check User Permissions
    • Verify your user account has the necessary permissions
    • Contact your administrator to update permissions
  2. Verify API Key Scope
    • Some API keys may have limited scope
    • Generate a new key with appropriate permissions
  3. Resource Access Rights
    • Ensure you have access to the specific customer/carrier data
    • Verify organization-level permissions

​
Data Integration Issues

Symptoms: Invoices not processing correctlySolutions:
  1. Check File Format
    • Supported formats: PDF, TIFF, PNG, JPEG
    • Maximum file size: 10MB per document
    • Ensure files are not corrupted
  2. Verify Email Configuration 
    From: [email protected]
To: [email protected]
Subject: [Invoice] or [Bill]
  3. Document Quality Requirements
    • Resolution: Minimum 300 DPI
    • Text must be clearly readable
    • No handwritten annotations over critical data
Symptoms: Shipment data not syncingSolutions:
  1. Connection Testing 
    curl -X GET "https://api.upwell.com/api/rest/shipments" \
  -H "Authorization: YOUR_API_KEY"
  2. Data Format Validation
    • Ensure shipment IDs match between systems
    • Verify date formats are ISO 8601 compliant
    • Check required fields are populated
  3. Webhook Configuration
    • Verify webhook URLs are accessible
    • Check SSL certificate validity
    • Confirm webhook authentication is configured
Symptoms: Payments not applying to invoicesSolutions:
  1. Check Payment Matching Rules
    • Verify invoice numbers match exactly
    • Ensure customer information is consistent
    • Review payment amount matching tolerances
  2. Review Bank Integration
    • Confirm bank feed is active and current
    • Check for connectivity issues
    • Verify account mapping is correct
  3. Manual Payment Application
    • Use the dashboard to manually apply payments
    • Document any discrepancies for future automation

​
Performance and Rate Limiting

Symptoms: API calls taking longer than expectedSolutions:
  1. Optimize Query Parameters 
    // Use pagination for large datasets
const response = await fetch(
  'https://api.upwell.com/api/rest/invoices?limit=50&offset=0'
);
  2. Implement Efficient Filtering 
    // Filter by date range to reduce data volume
const params = new URLSearchParams({
  'created_after': '2024-01-01',
  'created_before': '2024-01-31',
  'status': 'pending'
});
  3. Use Bulk Operations 
    // Process multiple items in a single request
const bulkUpdate = await fetch(
  'https://api.upwell.com/api/rest/bulk-invoices',
  {
    method: 'PUT',
    body: JSON.stringify({ invoices: invoiceArray })
  }
);
Symptoms: Getting 429 Too Many Requests errorsSolutions:
  1. Implement Exponential Backoff 
    import time
import random

def api_call_with_backoff(url, max_retries=5):
    for attempt in range(max_retries):
        response = requests.get(url)

        if response.status_code == 429:
            wait_time = (2 ** attempt) + random.uniform(0, 1)
            time.sleep(wait_time)
            continue

        return response
  2. Respect Rate Limit Headers 
    def check_rate_limit(response):
    remaining = int(response.headers.get('X-RateLimit-Remaining', 0))
    reset_time = int(response.headers.get('X-RateLimit-Reset', 0))

    if remaining < 10:
        current_time = time.time()
        sleep_time = reset_time - current_time
        if sleep_time > 0:
            time.sleep(sleep_time)

​
Data Quality and Validation

Symptoms: Getting 400 Bad Request with validation detailsSolutions:
  1. Required Field Validation 
    const requiredFields = ['customer_id', 'amount', 'due_date'];
const missingFields = requiredFields.filter(field => !invoiceData[field]);

if (missingFields.length > 0) {
  throw new Error(`Missing required fields: ${missingFields.join(', ')}`);
}
  2. Data Type Validation 
    def validate_invoice_data(data):
    if not isinstance(data.get('amount'), (int, float)) or data['amount'] <= 0:
        raise ValueError("Amount must be a positive number")

    if not re.match(r'^\d{4}-\d{2}-\d{2}$', data.get('due_date', '')):
        raise ValueError("Due date must be in YYYY-MM-DD format")
  3. Business Rule Validation
    • Check credit limits before creating invoices
    • Verify carrier contracts are active
    • Ensure payment terms are valid
Symptoms: Getting 404 Not Found for existing resourcesSolutions:
  1. Verify Resource IDs
    • Check for typos in UUIDs or reference numbers
    • Ensure you’re using the correct identifier type
    • Confirm the resource hasn’t been deleted
  2. Check Data Permissions
    • Verify you have access to the specific customer/carrier
    • Confirm organization-level data access
  3. Search Alternative Endpoints 
    # Search instead of direct lookup
curl "https://api.upwell.com/api/rest/invoices/search?number=INV-001" \
  -H "Authorization: YOUR_API_KEY"

​
Testing and Debugging

​
API Testing Tools

Basic Request Testing:
# Test authentication
curl -v -H "Authorization: YOUR_API_KEY" \
  https://api.upwell.com/api/rest/invoices

# Test with verbose output for debugging
curl -v -X POST https://api.upwell.com/api/rest/invoices \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"customer_id": "123", "amount": 100.00}'
Setting Up Postman:
  1. Import the Upwell OpenAPI specification
  2. Configure environment variables:
  3. Set up authentication in the Authorization tab
  4. Use the Collection Runner for batch testing

​
Logging and Monitoring

Essential Logging Information:
import logging

def log_api_request(method, url, status_code, response_time):
    logging.info(f"API Request: {method} {url} - {status_code} ({response_time}ms)")

    if status_code >= 400:
        logging.error(f"API Error: {status_code} - Check error response for details")
Key Metrics to Track:
  • Response times by endpoint
  • Error rates by error code
  • Rate limit utilization
  • Success/failure ratios
const metrics = {
  totalRequests: 0,
  successfulRequests: 0,
  averageResponseTime: 0,
  errorsByCode: {}
};

​
Getting Additional Help

​
Support Channels

Technical Support

For API and integration issues

API Documentation

Complete endpoint reference

Error Codes Reference

Detailed error code explanations

Implementation Guide

Step-by-step setup instructions

​
When Contacting Support

Include the following information in your support request:
  1. Error Details
    • Complete error message and code
    • Request timestamp
    • Endpoint being called
  2. Request Information
    • HTTP method and URL
    • Request headers (excluding API key)
    • Request body (if applicable)
  3. Environment Details
    • Programming language and version
    • Library/SDK versions
    • Network configuration (if relevant)
  4. Steps to Reproduce
    • Detailed steps that led to the issue
    • Expected vs. actual behavior
    • Frequency of occurrence

​
Best Practices for Smooth Operation

  1. Keep API Keys Secure
    • Never commit keys to version control
    • Use environment variables
    • Rotate keys regularly
  2. Implement Proper Error Handling
    • Handle all HTTP status codes appropriately
    • Implement retry logic for transient errors
    • Log errors for debugging
  3. Monitor API Usage
    • Track request volumes and patterns
    • Monitor rate limit usage
    • Set up alerts for unusual activity
  4. Test Thoroughly
    • Test error scenarios in addition to success cases
    • Use staging environment for integration testing
    • Validate data before sending to API
  5. Stay Updated
    • Subscribe to API change notifications
    • Review documentation updates
    • Test new features in staging first