Error Reference - Captain Data

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

Quick Reference Table

Status Code	Category	Retry?	What to Do
`200`	Success	—	Process the response data
`400`	Input	No — fix input	Check `error_label` and `message`, then fix your request
`401`	Auth	No — fix API key	Verify your `X-API-Key` header
`403`	Access	No — check permissions	Verify account permissions
`404`	Not Found	No	Resource doesn’t exist — no action needed
`429`	Rate Limit	Yes — with backoff	Wait for `Retry-After` header value, then retry
`500`	Server	Yes — with backoff	Retry 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:

Scope	Description	Typical Action
`input`	The input data provided is invalid	Fix the input format or value
`param`	A parameter in the request is invalid	Check parameter requirements in the docs
`auth`	Authentication or authorization issue	Verify your API key and permissions
`server`	Server-side error	Retry 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.

INVALID_INPUT

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.

BAD_PARAMETERS

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.

UNAUTHORIZED (401)

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.

FORBIDDEN (403)

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.

NOT_FOUND

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.

NO_RESULT

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.

INTERNAL_ERROR (500)

Description: An unexpected server error occurred.Resolution: Retry with exponential backoff. If persistent, contact support@captaindata.com with the error_ref value.

SERVICE_UNAVAILABLE (503)

Description: The service is temporarily unavailable.Resolution: Wait a few minutes and retry. This is typically a transient issue.

Best Practices

Always check error_label: Use this field to programmatically handle different error types.
Log the error_ref: This unique reference helps our support team investigate issues quickly.
Implement exponential backoff: For retryable errors (429, 500, 503), wait progressively longer between retries.
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 support@captaindata.com with the error_ref from your error response.

​Quick Reference Table

​Error Response Structure

​Understanding Error Scopes

​Handling Rate Limit Errors (429)

​Error Categories

​Input & Validation Errors (400)

​Authentication & Access Errors (401, 403)

​Not Found Errors (404)

​Server Errors (500, 503)

​Best Practices

Quick Reference Table

Error Response Structure

Understanding Error Scopes

Handling Rate Limit Errors (429)

Error Categories

Input & Validation Errors (400)

Authentication & Access Errors (401, 403)

Not Found Errors (404)

Server Errors (500, 503)

Best Practices