Overview

The Tuesday Leads API use standard HTTP status codes to indicate the success or failure of API requests. When an error occurs, the response will include a structured error message to help you understand and resolve the issue.

Error Response Format

All error responses follow this consistent structure:

{
    "statusCode": 400,
    "message": "Bad Request",
    "error": "Detailed error description"
}

Common Error Codes

400 - Bad Request

Invalid or missing required parameters in your request.

401 - Unauthorized

Invalid or missing API key in request headers.

402 - Insufficient Credits

Not enough credits available to complete the request.

404 - Not Found

The requested resource could not be found.

429 - Rate Limit Exceeded

Too many requests within the allowed time window.

500 - Internal Server Error

Something went wrong on our end. Try again later.

Detailed Error Examples

400 Bad Request

Missing Required Parameter:

{
    "statusCode": 400,
    "message": "Bad Request",
    "error": "Missing required parameter: linkedin_url"
}

Invalid Parameter Format:

{
    "statusCode": 400,
    "message": "Bad Request", 
    "error": "Invalid LinkedIn URL format"
}

Invalid Parameter Value:

{
    "statusCode": 400,
    "message": "Bad Request",
    "error": "include_email must be 'include' or 'exclude'"
}

401 Unauthorized

Missing API Key:

{
    "statusCode": 401,
    "message": "Unauthorized",
    "error": "API key is required"
}

Invalid API Key:

{
    "statusCode": 401,
    "message": "Unauthorized", 
    "error": "Invalid or missing API key"
}

402 Insufficient Credits

{
    "statusCode": 402,
    "message": "Insufficient credits",
    "error": "Not sufficient credit available for request. Required: 5, Available: 2"
}

404 Not Found

Resource Not Found:

{
    "statusCode": 404,
    "message": "Not Found",
    "error": "Profile not found for the provided LinkedIn URL"
}

Endpoint Not Found:

{
    "statusCode": 404,
    "message": "Not Found",
    "error": "API endpoint does not exist"
}

429 Rate Limit Exceeded

{
    "statusCode": 429,
    "message": "Rate Limit Exceeded",
    "error": "Too many requests within the limit. Try again in 60 seconds"
}

500 Internal Server Error

{
    "statusCode": 500,
    "message": "Internal Server Error",
    "error": "Something went wrong on our end"
}

Error Handling Best Practices

1. Always Check Status Codes

const response = await fetch(endpoint, options);

if (!response.ok) {
  const errorData = await response.json();
  console.error(`API Error ${response.status}:`, errorData.error);
  
  switch (response.status) {
    case 400:
      throw new Error(`Bad request: ${errorData.error}`);
    case 401:
      throw new Error('Authentication failed - check your API key');
    case 429:
      throw new Error('Rate limit exceeded - slow down requests');
    case 500:
      throw new Error('Server error - try again later');
    default:
      throw new Error(`Unexpected error: ${errorData.error}`);
  }
}

const data = await response.json();

2. Implement Retry Logic for Transient Errors

For 429 (rate limits) and 5xx (server errors), implement exponential backoff:

async function makeRequestWithRetry(url, options, maxRetries = 3) {
  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    try {
      const response = await fetch(url, options);
      
      // Success
      if (response.ok) {
        return await response.json();
      }
      
      // Don't retry client errors (4xx except 429)
      if (response.status >= 400 && response.status < 500 && response.status !== 429) {
        const errorData = await response.json();
        throw new Error(`Client error: ${errorData.error}`);
      }
      
      // Retry for 429 and 5xx
      if (response.status === 429 || response.status >= 500) {
        if (attempt === maxRetries) {
          const errorData = await response.json();
          throw new Error(`Max retries exceeded: ${errorData.error}`);
        }
        
        const delay = Math.min(1000 * Math.pow(2, attempt), 10000);
        console.log(`Retrying in ${delay}ms... (attempt ${attempt + 1})`);
        await new Promise(resolve => setTimeout(resolve, delay));
        continue;
      }
      
    } catch (error) {
      if (attempt === maxRetries) throw error;
      
      const delay = Math.min(1000 * Math.pow(2, attempt), 10000);
      await new Promise(resolve => setTimeout(resolve, delay));
    }
  }
}

3. Log Errors for Debugging

function logError(error, context) {
  console.error('API Error:', {
    timestamp: new Date().toISOString(),
    context: context,
    status: error.status,
    message: error.message,
    endpoint: error.endpoint
  });
}

Troubleshooting Common Issues

Getting Help

If you’re experiencing persistent errors or need additional assistance: