Error Responses

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();

import requests

response = requests.get(endpoint, headers=headers)

if response.status_code != 200:
    error_data = response.json()
    
    if response.status_code == 400:
        raise ValueError(f"Bad request: {error_data['error']}")
    elif response.status_code == 401:
        raise PermissionError("Authentication failed - check your API key")
    elif response.status_code == 429:
        raise Exception("Rate limit exceeded - slow down requests")
    elif response.status_code == 500:
        raise Exception("Server error - try again later")
    else:
        raise Exception(f"Unexpected error: {error_data['error']}")

data = 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

Authentication Problems

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

Rate Limiting Issues

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

Credit Exhaustion

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

Invalid Parameters

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

Data Not Found

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

Getting Started

Integrations

Overview

Error Response Format

Common Error Codes

400 - Bad Request

401 - Unauthorized

402 - Insufficient Credits

404 - Not Found

429 - Rate Limit Exceeded

500 - Internal Server Error

Detailed Error Examples

400 Bad Request

401 Unauthorized

402 Insufficient Credits

404 Not Found

429 Rate Limit Exceeded

500 Internal Server Error

Error Handling Best Practices

1. Always Check Status Codes

2. Implement Retry Logic for Transient Errors

3. Log Errors for Debugging

Troubleshooting Common Issues

Getting Help

Check System Status

API Reference

Dashboard

​Overview

​Error Response Format

​Common Error Codes

​400 - Bad Request

​401 - Unauthorized

​402 - Insufficient Credits

​404 - Not Found

​429 - Rate Limit Exceeded

​500 - Internal Server Error

​Detailed Error Examples

​400 Bad Request

​401 Unauthorized

​402 Insufficient Credits

​404 Not Found

​429 Rate Limit Exceeded

​500 Internal Server Error

​Error Handling Best Practices

​1. Always Check Status Codes

​2. Implement Retry Logic for Transient Errors

​3. Log Errors for Debugging

​Troubleshooting Common Issues

​Getting Help

Check System Status

API Reference

Dashboard

Overview

Error Response Format

Common Error Codes

400 - Bad Request

401 - Unauthorized

402 - Insufficient Credits

404 - Not Found

429 - Rate Limit Exceeded

500 - Internal Server Error

Detailed Error Examples

400 Bad Request

401 Unauthorized

402 Insufficient Credits

404 Not Found

429 Rate Limit Exceeded

500 Internal Server Error

Error Handling Best Practices

1. Always Check Status Codes

2. Implement Retry Logic for Transient Errors

3. Log Errors for Debugging

Troubleshooting Common Issues

Getting Help