RocketReach Python Library

Common errors

• ModuleNotFoundError: No module named 'rocketreach'

  cause The 'rocketreach' Python package has not been installed in your current environment.
  fix Install the library using pip: `pip install rocketreach`

• rocketreach.errors.RocketReachAPIError: Invalid API Key provided.

  cause The API key configured for the `Gateway` client is incorrect, expired, or missing. This can also occur if you try to use a production key in the sandbox environment or vice-versa.
  fix Verify your `ROCKETREACH_API_KEY` environment variable or the API key passed to `rocketreach.Gateway()` is correct. Ensure it matches the environment (production or sandbox) you intend to use. You can generate/view your API key on the RocketReach website in your API settings.

• NameError: name 'rocketreach' is not defined

  cause You are trying to use objects or functions from the `rocketreach` library without importing it first.
  fix Add `import rocketreach` at the top of your Python script. If using specific classes like `Gateway`, use `from rocketreach import Gateway`.

• AttributeError: 'NoneType' object has no attribute 'get' (or 'search')

  cause This typically happens if the `rocketreach.Gateway` object itself was not correctly initialized (e.g., due to a missing API key) and thus returned `None` or an incomplete object, or if you're trying to access a non-existent method/service.
  fix Ensure the `Gateway` object is properly initialized with a valid API key. For instance, `rr = rocketreach.Gateway(api_key=os.environ.get('ROCKETREACH_API_KEY', ''))` should be correctly configured. Double-check method names like `account.get()` or `person.search()` against the documentation.

Warnings

• gotcha RocketReach API lookups consume credits from your account. Be mindful of usage, especially when performing bulk operations or iterative searches, as this can lead to unexpected charges.
  Fix: Monitor your RocketReach account's credit usage. The library's `rr.account.get()` method can fetch remaining lookups. Understand the pricing model before running extensive queries.
• gotcha The default `person.lookup()` method is blocking, meaning it will poll the API until contact information is found or the lookup times out. For asynchronous workflows, pass `block=False` and use `checkStatus()` manually.
  Fix: For non-blocking operations: `result = rr.person.lookup(person_id=123, block=False)`. Then, periodically call `rr.person.checkStatus(person_id=result.person.id)` until the status is complete.
• gotcha The RocketReach API has a rate limit (e.g., 250 requests per minute). Exceeding this limit will result in a `429 Too Many Requests` status code.
  Fix: Implement a retry mechanism with exponential backoff for API calls. Check the error message for `Retry-After` headers if provided, or simply wait a few seconds before retrying.
• breaking The default branch of the `rocketreach/rocketreach_python` GitHub repository switched from `master` to `main` on 2025/08/13. This affects how you clone or pull updates if you are tracking the default branch.
  Fix: Update your local Git configurations for any forks or clones to track the `main` branch: `git branch -m master main; git fetch origin; git branch -u origin/main main; git remote set-head origin -a`

Install

• pip install rocketreach Install with pip

Imports

• Gateway

  from rocketreach import Gateway

• GatewayConfig

  from rocketreach import GatewayConfig

• GatewayEnvironment

  from rocketreach import GatewayEnvironment

• rocketreach
  wrong:

  from rocketreach import *

  correct:

  import rocketreach

  While 'from rocketreach import *' works, it's generally discouraged in production code due to potential name collisions. Prefer explicit imports or 'import rocketreach' and qualify names.

Quickstart

This quickstart initializes the RocketReach client using an API key from an environment variable, then demonstrates fetching account details and performing a basic person search. Be aware that person searches consume lookup credits on your RocketReach account.

import rocketreach
import os

# Ensure your RocketReach API key is set as an environment variable
api_key = os.environ.get('ROCKETREACH_API_KEY', '')

if not api_key:
    print("Warning: ROCKETREACH_API_KEY environment variable not set. Quickstart may fail.")
    print("Please set it: export ROCKETREACH_API_KEY='your_api_key'")
else:
    try:
        # Initialize the RocketReach Gateway
        rr = rocketreach.Gateway(api_key=api_key)

        # Example 1: Get account details
        account_result = rr.account.get()
        if account_result.is_success:
            print("Account details:", account_result.account)
        else:
            print("Failed to retrieve account details:", account_result.error)

        # Example 2: Search for a person (Note: This operation consumes lookup credits)
        # Replace 'Google' and 'Software Engineer' with your target criteria
        print("\nAttempting a person search (consumes credits)...")
        person_search_query = rr.person.search().filter(
            current_employer='Google',
            current_title='Software Engineer'
        )
        search_results = person_search_query.execute()

        if search_results.is_success:
            print(f"Found {len(search_results.people)} matching people:")
            for person in search_results.people:
                emails_display = ', '.join([e.value for e in person.emails]) if person.emails else 'No email'
                print(f"  - Name: {person.name}, Title: {person.current_title}, Company: {person.current_employer}, Emails: {emails_display}")
        else:
            print("Failed to perform person search:", search_results.error)

    except Exception as e:
        print(f"An unexpected error occurred: {e}")