> ## Documentation Index
> Fetch the complete documentation index at: https://docs.captaindata.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Error Reference

> Complete reference for all error codes, HTTP status codes, and troubleshooting guidance for the Captain Data API.

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:

```json theme={null}
{
  "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:**

```javascript theme={null}
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');
}
```

<Tip>
  For detailed rate limit information by plan tier, see our [Rate Limits documentation](/v1/rate-limits).
</Tip>

***

## Error Categories

### Input & Validation Errors (400)

These errors occur when your request contains invalid data. **Do not retry** — fix the input first.

<AccordionGroup>
  <Accordion title="INVALID_INPUT" icon="circle-xmark">
    **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.
  </Accordion>

  <Accordion title="BAD_PARAMETERS" icon="sliders">
    **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.
  </Accordion>
</AccordionGroup>

### Authentication & Access Errors (401, 403)

These errors indicate permission or authentication issues.

<AccordionGroup>
  <Accordion title="UNAUTHORIZED (401)" icon="key">
    **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](https://app.captaindata.com/developers).
  </Accordion>

  <Accordion title="FORBIDDEN (403)" icon="lock">
    **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.
  </Accordion>
</AccordionGroup>

### Not Found Errors (404)

These errors indicate the requested resource doesn't exist.

<AccordionGroup>
  <Accordion title="NOT_FOUND" icon="magnifying-glass">
    **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**.
  </Accordion>

  <Accordion title="NO_RESULT" icon="inbox">
    **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.
  </Accordion>
</AccordionGroup>

### Server Errors (500, 503)

These errors indicate something went wrong on our end.

<AccordionGroup>
  <Accordion title="INTERNAL_ERROR (500)" icon="server">
    **Description**: An unexpected server error occurred.

    **Resolution**: Retry with exponential backoff. If persistent, contact [support@captaindata.com](mailto:support@captaindata.com) with the `error_ref` value.
  </Accordion>

  <Accordion title="SERVICE_UNAVAILABLE (503)" icon="clock">
    **Description**: The service is temporarily unavailable.

    **Resolution**: Wait a few minutes and retry. This is typically a transient issue.
  </Accordion>
</AccordionGroup>

***

## 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.

<Info>
  If you encounter persistent errors or need help debugging, contact [support@captaindata.com](mailto:support@captaindata.com) with the `error_ref` from your error response.
</Info>