Skip to main content
This page provides a comprehensive reference for understanding and handling errors across the Captain Data API.

​
Quick Reference Table

Status CodeCategoryRetry?What to Do
200Success—Process the response data
400InputNo — fix inputCheck error_label and message, then fix your request
401AuthNo — fix API keyVerify your X-API-Key header
403AccessNo — check permissionsVerify account permissions
404Not FoundNoResource doesn’t exist — no action needed
429Rate LimitYes — with backoffWait for Retry-After header value, then retry
500ServerYes — with backoffRetry after a short delay

​
Error Response Structure

The API uses a consistent error response format across all endpoints. When an error occurs, you’ll receive a response with the following structure: 
{
  "error_label": "INVALID_INPUT",
  "error_scope": "input",
  "error_ref": "ERR-12345",
  "message": "The provided input is invalid. Please check your request and try again.",
  "status_code": 400,
  "params": {}
}
Each error response includes:
  • error_label: A machine-readable identifier for the error type
  • error_scope: Indicates which part of the request caused the error (e.g., “input”, “auth”, “server”)
  • error_ref: A unique reference code for tracking and debugging
  • message: A human-readable description of the error
  • status_code: The HTTP status code
  • params: Additional error parameters (if any)

​
Understanding Error Scopes

Every error response includes an error_scope field that indicates what caused the error:
ScopeDescriptionTypical Action
inputThe input data provided is invalidFix the input format or value
paramA parameter in the request is invalidCheck parameter requirements in the docs
authAuthentication or authorization issueVerify your API key and permissions
serverServer-side errorRetry with backoff, or contact support

​
Handling Rate Limit Errors (429)

When you exceed rate limits, you’ll receive a 429 Too Many Requests response. Use the Retry-After header to know when to retry. Example Implementation: 
async function callWithRetry(requestFn, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      return await requestFn();
    } catch (error) {
      if (error.status === 429) {
        // Use Retry-After header if available, otherwise exponential backoff
        const retryAfter = error.headers['retry-after'];
        const delay = retryAfter 
          ? parseInt(retryAfter) * 1000 
          : Math.min(1000 * Math.pow(2, attempt), 30000);
        
        console.log(`Rate limited. Waiting ${delay}ms before retry...`);
        await new Promise(resolve => setTimeout(resolve, delay));
      } else {
        throw error; // Non-retryable error
      }
    }
  }
  throw new Error('Max retries exceeded');
}
For detailed rate limit information by plan tier, see our Rate Limits documentation.

​
Error Categories

​
Input & Validation Errors (400)

These errors occur when your request contains invalid data. Do not retry — fix the input first.
Description: The input data is invalid or incorrectly formatted.Common Causes:
  • Invalid URL format
  • Missing required identifiers
  • Malformed query parameters
Resolution: Check the message field for details, then verify your input against the endpoint’s documentation.
Description: One or more parameters in the request are invalid.Common Causes:
  • Parameter value out of allowed range
  • Incompatible parameter combinations
  • Wrong data type for a parameter
Resolution: Review parameter constraints in the endpoint documentation.

​
Authentication & Access Errors (401, 403)

These errors indicate permission or authentication issues.
Description: Your API key is invalid or missing.Common Causes:
  • Missing X-API-Key header
  • Invalid or expired API key
  • Typo in the API key
Resolution: Verify your API key in Developer Settings.
Description: You don’t have access to this resource.Common Causes:
  • Insufficient plan permissions
  • Resource restricted to specific accounts
Resolution: Check your subscription plan includes access to this endpoint.

​
Not Found Errors (404)

These errors indicate the requested resource doesn’t exist.
Description: The resource you requested doesn’t exist or is no longer available.Common Causes:
  • Profile has been deleted or deactivated
  • Company page no longer exists
  • Invalid identifier (typo in URL or ID)
Resolution: Verify the resource URL/ID is correct. If valid, the resource may have been removed — no retry needed.
Description: The query returned no results.Common Causes:
  • Search criteria too narrow
  • No matching data found
Resolution: Treat as an empty result set. Consider broadening your search criteria.

​
Server Errors (500, 503)

These errors indicate something went wrong on our end.
Description: An unexpected server error occurred.Resolution: Retry with exponential backoff. If persistent, contact [email protected] with the error_ref value.
Description: The service is temporarily unavailable.Resolution: Wait a few minutes and retry. This is typically a transient issue.

​
Best Practices

  1. Always check error_label: Use this field to programmatically handle different error types.
  2. Log the error_ref: This unique reference helps our support team investigate issues quickly.
  3. Implement exponential backoff: For retryable errors (429, 500, 503), wait progressively longer between retries.
  4. Don’t retry input errors: 400-level errors (except 429) require fixing your request, not retrying.
If you encounter persistent errors or need help debugging, contact [email protected] with the error_ref from your error response.