---
updatedAt: 2026-09-14T20:57:12.000Z
agentTools:
  projectIndex: https://docs.rocketreach.co/llms.txt
---

# Errors

Every tool error uses a consistent shape: `isError: true`, a human-readable text field the AI can surface to the user, and a machine-readable `error_code` in `_meta` for programmatic branching.

```json
{
  "content": [
    { "type": "text", "text": "You've run out of lookup credits. Visit your RocketReach account to add more." }
  ],
  "_meta": { "error_code": "insufficient_credits", "credit_type": "standard_lookup" },
  "isError": true
}
```

## Error codes

| `error_code`           | HTTP equivalent | When it happens                                                                                                                                                              |
| ---------------------- | --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `auth_required`        | 401             | No Bearer token, expired token, wrong audience, or v2 rejected the request based on user state (unverified email, suspended account, etc.)                                   |
| `insufficient_credits` | 402             | The credit type required for this operation has a zero balance — either depleted or never issued on the account. See the `credit_type` extra field to know which type failed |
| `not_found`            | 404             | The supplied identifier did not resolve to any profile or company                                                                                                            |
| `lookup_failed`        | —               | The profile resolved, the search ran to completion, but no contact information was found. Terminal — retrying the same identifier will not help                              |
| `rate_limited`         | 429             | RocketReach API rate limit reached. Check `retry_after_seconds` in `_meta`                                                                                                   |
| `validation_error`     | 400             | A parameter failed input validation. Check `field` and `reason` in `_meta`                                                                                                   |
| `service_error`        | 5xx             | Unexpected backend failure. Retry after a moment                                                                                                                             |

## Extra fields in `_meta`

| Code                   | Extra fields                                                                                                                                                                               | Example                                                                                             |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------- |
| `insufficient_credits` | `credit_type` — which of the seven credit types was missing: `standard_lookup`, `premium_lookup`, `phone_lookup`, `person_enrich`, `person_export`, `company_export`, `email_verification` | `{ "error_code": "insufficient_credits", "credit_type": "company_export" }`                         |
| `rate_limited`         | `retry_after_seconds` — how long to wait before retrying                                                                                                                                   | `{ "error_code": "rate_limited", "retry_after_seconds": 30 }`                                       |
| `validation_error`     | `field` — which parameter failed; `reason` — human-readable explanation                                                                                                                    | `{ "error_code": "validation_error", "field": "email", "reason": "must be a valid email address" }` |

When `credit_type` is `email_verification`, the message carries a link to purchase more verification credits so the user can add credits and retry.

## Non-error responses

One intermediate state looks like an error but is not — `isError` is `false`.

`status: "pending"` — the lookup is still in progress. Call `check_person_status` with the `profile_id` to retrieve results once ready. No credit is consumed on the poll.

## `auth_required` detail

`auth_required` covers two distinct cases:

* **Token missing or invalid** — no Bearer token in the request, the token is expired, the audience does not match the MCP server URL, or the token was signed with an unrecognized key. The client should re-authorize.
* **User state blocked** — the token is cryptographically valid but v2 rejected the request because of account state: email not verified, account suspended, or region unavailable. The error text describes which gate blocked the request and what the user should do.

## Notes for custom client builders

Error messages in `content[0].text` are user-readable — surface them to the end user as-is. Do not parse the text for machine logic; use `_meta.error_code` instead.

`lookup_failed` and `not_found` are terminal — retrying the same identifier will not produce a different result. Log or surface the message and move on.

Per-record `status: "failed"` from `check_person_status` (when called with an array of profile IDs) is not a tool-level error — the array itself is returned as a success, and individual records that failed to resolve carry `status: "failed"` inside the array.