Error Handling

Understanding and handling API errors effectively for robust integrations.

Error Response Format

All API errors follow a consistent JSON format:

{
  "error": {
    "type": "VALIDATION_ERROR",
    "message": "The linkedin_url field is required",
    "code": "E1001",
    "details": {
      "field": "linkedin_url",
      "value": null,
      "constraint": "required"
    },
    "request_id": "req_2Xk9Lm3Np",
    "timestamp": "2025-01-20T14:30:00Z"
  }
}

Error Object Fields

HTTP Status Codes

Sales Webhooks uses standard HTTP status codes to indicate success or failure:

Success Codes

Client Error Codes

Server Error Codes

Error Types Reference

Common error types and how to handle them:

Authentication Errors

{
  "error": {
    "type": "AUTHENTICATION_FAILED",
    "message": "Invalid API key",
    "code": "E1101",
    "details": {
      "hint": "Check that your API key is correct and active"
    }
  }
}

Validation Errors

{
  "error": {
    "type": "VALIDATION_ERROR",
    "message": "Invalid LinkedIn URL format",
    "code": "E1201",
    "details": {
      "field": "linkedin_url",
      "value": "not-a-url",
      "constraint": "url_format",
      "expected": "https://linkedin.com/in/username"
    }
  }
}

Rate Limit Errors

{
  "error": {
    "type": "RATE_LIMIT_EXCEEDED",
    "message": "API rate limit exceeded",
    "code": "E1301",
    "details": {
      "limit": 50,
      "remaining": 0,
      "reset_at": "2025-01-20T15:00:00Z",
      "retry_after": 234
    }
  }
}

Resource Errors

{
  "error": {
    "type": "RESOURCE_NOT_FOUND",
    "message": "Subscription not found",
    "code": "E1401",
    "details": {
      "resource": "subscription",
      "id": "sub_9Yx7Kj2Mn"
    }
  }
}

Handling Errors in Code

JavaScript/Node.js

async function createSubscription(linkedinUrl) {
  try {
    const subscription = await client.subscriptions.create({
      entity_type: 'contact',
      linkedin_url: linkedinUrl
    });
    return subscription;
  } catch (error) {
    // Check if it's an API error
    if (error.response) {
      const apiError = error.response.data.error;
      
      switch (apiError.type) {
        case 'VALIDATION_ERROR':
          console.error(`Invalid data: ${apiError.message}`);
          // Show validation error to user
          break;
          
        case 'RATE_LIMIT_EXCEEDED':
          const retryAfter = apiError.details.retry_after;
          console.log(`Rate limited. Retrying in ${retryAfter}s`);
          await sleep(retryAfter * 1000);
          return createSubscription(linkedinUrl); // Retry
          
        case 'DUPLICATE_RESOURCE':
          console.log('Subscription already exists');
          // Handle duplicate gracefully
          break;
          
        default:
          console.error(`API Error: ${apiError.message}`);
          throw error;
      }
    } else {
      // Network or other error
      console.error('Network error:', error.message);
      throw error;
    }
  }
}

Python

from saleswebhooks import SalesWebhooks, APIError
import time

def create_subscription_with_retry(client, linkedin_url, max_retries=3):
    """Create subscription with automatic retry on rate limits"""
    
    for attempt in range(max_retries):
        try:
            subscription = client.subscriptions.create(
                entity_type='contact',
                linkedin_url=linkedin_url
            )
            return subscription
            
        except APIError as e:
            if e.error_type == 'RATE_LIMIT_EXCEEDED':
                retry_after = e.details.get('retry_after', 60)
                print(f"Rate limited. Waiting {retry_after}s...")
                time.sleep(retry_after)
                continue
                
            elif e.error_type == 'VALIDATION_ERROR':
                print(f"Validation error: {e.message}")
                print(f"Field: {e.details.get('field')}")
                raise
                
            elif e.error_type == 'DUPLICATE_RESOURCE':
                print("Subscription already exists")
                return None
                
            else:
                print(f"API Error: {e.message}")
                raise
                
        except Exception as e:
            print(f"Unexpected error: {e}")
            if attempt < max_retries - 1:
                time.sleep(2 ** attempt)  # Exponential backoff
            else:
                raise

Error Recovery Strategies

Common Error Scenarios

Webhook Delivery Failures

{
  "error": {
    "type": "WEBHOOK_DELIVERY_FAILED",
    "message": "Failed to deliver webhook after 4 attempts",
    "code": "E1501",
    "details": {
      "webhook_id": "whd_3Zk1No5Pr",
      "endpoint_url": "https://your-app.com/webhook",
      "last_error": "Connection timeout",
      "attempts": 4,
      "first_attempt": "2025-01-20T14:00:00Z",
      "last_attempt": "2025-01-20T14:00:36Z"
    }
  }
}

Subscription Limits

{
  "error": {
    "type": "LIMIT_EXCEEDED",
    "message": "Subscription limit reached for your plan",
    "code": "E1601",
    "details": {
      "limit": 1000,
      "current": 1000,
      "plan": "professional",
      "upgrade_url": "https://console.saleswebhooks.com/billing/upgrade"
    }
  }
}

LinkedIn Data Errors

{
  "error": {
    "type": "LINKEDIN_ERROR",
    "message": "LinkedIn profile is private or doesn't exist",
    "code": "E1701",
    "details": {
      "linkedin_url": "https://linkedin.com/in/private-user",
      "reason": "profile_private",
      "suggestion": "Ensure the profile is public and URL is correct"
    }
  }
}

Troubleshooting Guide

Getting Help

If you continue to experience errors:

• Check our troubleshooting guide
• Search our GitHub issues
• Contact support with your request ID at support@saleswebhooks.com