Error Handling

Understand API errors, error codes, and how to handle them gracefully in your applications.

Error Response Format

All API errors follow a consistent format:

{
  "success": false,              // Always false for errors
  "error": {
    "code": "ERROR_CODE",        // Machine-readable error code
    "message": "Description",    // Human-readable error message
    "details": {                 // Optional additional context
      "field": "specific info"
    }
  },
  "meta": {
    "request_id": "req_...",     // Unique request identifier
    "timestamp": "2025-01-15T10:30:00Z",
    "version": "v1"
  }
}

HTTP Status Codes

The API uses standard HTTP status codes:

Error Codes

Authentication Errors

Request Errors

Rate Limiting Errors

Conversion Errors

Server Errors

Common Error Scenarios

Scenario 1: Invalid API Key

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or missing API key"
  }
}

# Correct format
curl https://agentsfordata.com/api/public/v1/convert/formats \
  -H "Authorization: Bearer tablab_api_xxxxx"

# Not this
-H "Authorization: tablab_api_xxxxx"  # Missing "Bearer"
-H "X-API-Key: tablab_api_xxxxx"       # Wrong header name

Scenario 2: Unsupported Format

{
  "success": false,
  "error": {
    "code": "UNSUPPORTED_FORMAT",
    "message": "The format 'pdf' is not supported",
    "details": {
      "format": "pdf"
    }
  }
}

curl https://agentsfordata.com/api/public/v1/convert/formats \
  -H "Authorization: Bearer YOUR_KEY"

Scenario 3: File Not Found

{
  "success": false,
  "error": {
    "code": "FILE_NOT_FOUND",
    "message": "Source file not found",
    "details": {
      "file_path": "2025-01-15/abc123/source-file.csv"
    }
  }
}

Scenario 4: Rate Limit Exceeded

{
  "success": false,
  "error": {
    "code": "RATE_LIMITED",
    "message": "Rate limit exceeded for this endpoint",
    "details": {
      "limit": 10,
      "window": "minute",
      "retry_after": 45
    }
  }
}

if (response.status === 429) {
  const retryAfter = data.error.details.retry_after;
  console.log(`Waiting ${retryAfter} seconds...`);
  await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
  // Retry request
}

Error Handling Best Practices

1. Always Check the Success Field

const data = await response.json();
if (!data.success) {
  console.error('API Error:', data.error.code, data.error.message);
  // Handle error based on error code
  switch (data.error.code) {
    case 'UNAUTHORIZED':
      // Redirect to login or show API key error
      break;
    case 'RATE_LIMITED':
      // Implement retry with backoff
      break;
    case 'UNSUPPORTED_FORMAT':
      // Show user error about format
      break;
    default:
      // Generic error handling
  }
}

2. Save Request IDs for Debugging

if (!data.success) {
  const requestId = data.meta.request_id;
  console.error(`Error ${data.error.code}: ${data.error.message}`);
  console.error(`Request ID: ${requestId}`);
  
  // Save to logs for support team
  logError({
    code: data.error.code,
    message: data.error.message,
    requestId: requestId,
    timestamp: new Date()
  });
}

3. Implement Exponential Backoff

async function fetchWithRetry(url, options, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      const response = await fetch(url, options);
      const data = await response.json();
      
      if (response.ok && data.success) {
        return data;
      }
      
      // Don't retry client errors (except 429)
      if (response.status >= 400 && response.status < 500 && response.status !== 429) {
        throw new Error(data.error.message);
      }
      
      // Retry on server errors and rate limits
      if (i < maxRetries - 1) {
        const delay = Math.min(1000 * Math.pow(2, i), 32000);
        await new Promise(resolve => setTimeout(resolve, delay));
        continue;
      }
      
      throw new Error(data.error.message);
      
    } catch (error) {
      if (i === maxRetries - 1) throw error;
    }
  }
}

4. Validate Before Sending

// Validate format before making API call
const supportedFormats = ['csv', 'json', 'xlsx', 'parquet', 'tsv'];

function validateConversion(sourceFormat, destFormat) {
  if (!supportedFormats.includes(sourceFormat)) {
    throw new Error(`Unsupported source format: ${sourceFormat}`);
  }
  if (!supportedFormats.includes(destFormat)) {
    throw new Error(`Unsupported destination format: ${destFormat}`);
  }
  if (sourceFormat === destFormat) {
    throw new Error('Source and destination formats must be different');
  }
}

// Use before API call
try {
  validateConversion('csv', 'json');
  // Make API call
} catch (error) {
  console.error('Validation error:', error.message);
  // Show user-friendly error without making API call
}

5. Handle Network Errors

try {
  const response = await fetch(url, options);
  const data = await response.json();
  // Handle response
} catch (error) {
  if (error.name === 'TypeError' && error.message === 'Failed to fetch') {
    console.error('Network error: Check your internet connection');
  } else if (error.name === 'AbortError') {
    console.error('Request timeout');
  } else {
    console.error('Unexpected error:', error);
  }
}

Getting Help

If you encounter errors you can't resolve:

1. Check this error reference for solutions
2. Review the Getting Started guide
3. Verify your request matches the endpoint schemas
4. Check our status page for ongoing incidents
5. Contact support with your request_id