Responses & Errors

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

Example API Responses

Success Example

{
  "id": 5244,
  "status": "complete",
  "name": "John Doe",
  "current_employer": "Google",
  "current_title": "Software Engineer",
  "emails": [
    {
      "email": "[email protected]",
      "type": "professional",
      "valid": "true"
    }
  ]
}

Error Example

{
  "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:

Go to RocketReach Account Settings →API Usage & Settings
Check the API Recent Error section
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 [email protected]

Example: Handling Rate Limits in 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)