Skip to main content

​
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

Symptoms: Getting 401 Unauthorized errorsSolutions:
  • Verify your API key is correct and properly included in the X-API-KEY header
  • Check that your API key hasn’t expired or been revoked
  • Ensure you’re not accidentally including extra spaces or characters
  • Generate a new API key if needed
Symptoms: Getting 429 Rate Limit Exceeded errorsSolutions:
  • Implement request throttling in your application
  • Use exponential backoff for retries
  • Consider upgrading your plan for higher limits
  • Distribute requests over time rather than in bursts
Symptoms: Getting 402 Insufficient Credits errorsSolutions:
  • Check your credit balance in the Tuesday dashboard
  • Only request enrichment data when necessary
  • Consider upgrading your plan
  • Implement credit usage monitoring
Symptoms: Getting 400 Bad Request errorsSolutions:
  • Verify all required parameters are included
  • Check parameter formats (especially LinkedIn URLs)
  • Ensure enum values are correct (e.g., “include” not “true”)
  • Review the API documentation for correct parameter names
Symptoms: Getting 404 Not Found errorsSolutions:
  • Verify the LinkedIn URL is publicly accessible
  • Check that the profile or company exists
  • Ensure URLs are properly encoded
  • Try alternative identifiers if available

​
Getting Help

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

Check System Status

Monitor our system status and uptime

API Reference

Review detailed API documentation

Dashboard

Monitor your usage and credits
⌘I