---
updatedAt: 2026-09-14T21:03:19.000Z
---

Fetch the complete documentation index at: https://docs.rocketreach.co/llms.txt. Use this file to discover all available pages before exploring further. Append .md to any documentation page URL to get its markdown version.

# Responses & Errors

The RocketReach API allows you to programmatically search and retrieve contact information for professionals and companies. This guide will help you understand API responses, error codes, rate limits, and troubleshooting steps.

## Key Takeaways

* RocketReach API responses contain status codes and structured data for processing.
* Error handling is essential for managing unsuccessful API requests.
* Rate limits apply—exceeding them triggers a **429 Too Many Requests** error.
* Webhooks help automate workflows and reduce unnecessary polling.
* Troubleshooting tools like API logs and error messages can help diagnose issues.
* Track API usage in the RocketReach API **Settings** dashboard.

***

## Understanding RocketReach API Responses

Each API request returns a **response** with a **status code** and structured **data**. Understanding these responses helps you determine the success or failure of a request.

***

## Common API Response Codes

| Status Code | Meaning               | Description                                                 |
| ----------- | --------------------- | ----------------------------------------------------------- |
| **200 OK**  | Success               | Request was successful, and data is returned.               |
| **400**     | Bad Request           | The request is malformed or missing required parameters.    |
| **401**     | Unauthorized          | API Key is missing or invalid.                              |
| **402**     | Payment Required      | Credits exhausted.                                          |
| **403**     | Forbidden             | API Key lacks permission to perform this action.            |
| **404**     | Not Found             | The requested resource (e.g., profile) does not exist.      |
| **429**     | Too Many Requests     | API request limit reached—slow down requests.               |
| **500**     | Internal Server Error | Unexpected error on RocketReach’s servers. Try again later. |

**Tip**: Always check the **response body** for additional error details.

***

### 402 Payment Required

Returned by `POST /api/v2/email/verify` when your email verification credit balance is empty. The body names the credit pool and where to buy more:

```json
{
  "detail": "You do not have enough Email Verification credits to complete this request. Purchase more at https://rocketreach.co/verify/purchase_credits.",
  "error_code": 202,
  "credit_type": "email_verification",
  "purchase_url": "https://rocketreach.co/verify/purchase_credits"
}
```

Read `credit_type` rather than matching on `detail` — it tells you which balance to top up, and the wording of `detail` can change. `error_code` is `202`, RocketReach's insufficient-credits code.

Running out of **lookup** credits is different: the search and lookup endpoints return `403 Forbidden` with an explanatory `detail` and no structured credit fields.

## Example API Responses

### Success Example

```json
{
  "id": 5244,
  "status": "complete",
  "name": "John Doe",
  "current_employer": "Google",
  "current_title": "Software Engineer",
  "emails": [
    {
      "email": "johndoe@google.com",
      "type": "professional",
      "valid": "true"
    }
  ]
}
```

### Error Example

```json
{
  "status": 401,
  "message": "Invalid API Key"
}
```

***

## Troubleshooting Common API Issues

Errors can occur due to authentication failures, invalid parameters, or rate limit violations.

### Authentication Errors (401 Unauthorized)

| Issue                 | Possible Causes            | Solution                                                 |
| --------------------- | -------------------------- | -------------------------------------------------------- |
| Invalid API Key (401) | API Key missing or invalid | Verify API Key is included correctly in request headers. |

### Bad Requests (400)

| Issue       | Possible Causes            | Solution                                                   |
| ----------- | -------------------------- | ---------------------------------------------------------- |
| Bad Request | Missing/invalid parameters | Review the API docs and ensure parameters are well-formed. |

### Rate Limit Errors (429)

| Issue             | Cause                  | Solution                                           |
| ----------------- | ---------------------- | -------------------------------------------------- |
| Too Many Requests | Request limit exceeded | Slow down or upgrade your plan. See example below. |

### Resource Not Found (404)

| Issue           | Cause                            | Solution                      |
| --------------- | -------------------------------- | ----------------------------- |
| Not Found (404) | Profile or company doesn’t exist | Check your search parameters. |

### Server Errors (500)

| Issue                 | Cause                   | Solution                           |
| --------------------- | ----------------------- | ---------------------------------- |
| Internal Server Error | Temporary backend issue | Retry the request after some time. |

***

## Checking API Error Logs

To view recent errors and usage:

1. Go to RocketReach **Account Settings →[API Usage & Settings](https://rocketreach.co/account?section=nav_gen_api)**
2. Check the **API Recent Error** section
3. Use the data to adjust your API calls and parameters accordingly

***

## Handling Rate Limit Errors

If you get a **429 Too Many Requests** response:

* Check the `Retry-After` header to know how long to wait
* Implement request throttling/delays in your code
* Use **webhooks** to reduce the need for polling
* Upgrade to a higher API plan — contact <sales@rocketreach.co>

***

## Example: Handling Rate Limits in Python

```python
import time
import requests

api_key = "YOUR_API_KEY"
url = "https://api.rocketreach.co/api/v2/person/lookup"
headers = {"Api-Key": api_key}
params = {"name": "John Doe"}

response = requests.get(url, headers=headers, params=params)

if response.status_code == 429:
    retry_after = int(response.headers.get("Retry-After", 5))
    print(f"Rate limit exceeded. Retrying in {retry_after} seconds...")
    time.sleep(retry_after)
    response = requests.get(url, headers=headers, params=params)
```