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

# Error codes

> Every Seamless.AI API error: HTTP status, error code, whether to retry, and how to fix it. Covers v1, v2, research poll statuses, and endpoint-specific errors.

Use this page to handle every error the Seamless.AI API returns. Each row says whether a retry can succeed and what to change if it can't. Agents should branch on the HTTP status first, then on `code` where one is present.

## Error body shapes

Error bodies are not uniform. Check for `code` first, then read `msg`, falling back to `message`. Extra fields such as `status`, `type`, and `data` appear on some errors and can be ignored.

```json 400 validation theme={null}
{
  "status": 400,
  "type": "validationError",
  "code": "invalidArguments",
  "msg": "page can not be a negative number",
  "message": "page can not be a negative number",
  "path": "page"
}
```

```json 401 authentication theme={null}
{
  "msg": "Unauthorized"
}
```

```json 422 credits or license theme={null}
{
  "status": 422,
  "code": "insufficientCredits",
  "msg": "Insufficient credit amount.",
  "message": "Insufficient credit amount.",
  "data": { "productCategory": "...", "additionalCreditsNeeded": 40 }
}
```

```json 429 rate limit theme={null}
{
  "code": "rateLimitExceeded",
  "message": "Rate limit exceeded. Please wait and try again."
}
```

## HTTP status codes

| Status | Meaning | Retry? | What to do |
| - | - | - | - |
| `400` | Invalid request: a bad filter value or a missing required field | No | Fix the request. The `message` names the problem. (Search `limit` above 500 is reduced to 500, not rejected.) |
| `401` | Missing, invalid, expired, or revoked API key or access token | No | Send `Token: YOUR_API_KEY`, or refresh the OAuth token. See [API keys](https://docs.seamless.ai/authentication/api-keys.md). |
| `403` | OAuth token lacks the required scope (`insufficientScope`), a gated feature is not enabled for your org (`noFeatureAccess`), or contact research asked for `researchTypes` your org doesn't allow | No | Re-authorize with the scope for the version you call — `publicAPI.v1.all` (v1) or `publicAPI.v2.all` (v2). `noFeatureAccess` means Seamless has not enabled that feature (for example Public API v2) for your organization; contact support. See [OAuth](https://docs.seamless.ai/authentication/oauth.md). For a `researchTypes` rejection, read `code` in the table below. |
| `404` | Wrong path, or the record ID doesn't exist (list, saved search, campaign, step, task, template, email, contact) | No | Check the base URL and the ID. |
| `409` | A bulk email send with the same `Idempotency-Key` is still in progress | Yes, later | Wait, then repeat with the same key and body to get the original job. |
| `422` | Not enough credits, no API license, or a validation error | No | Read `code`. See the table below. |
| `429` | Rate limit reached (`rateLimitExceeded`) | Yes | Wait until the `X-RateLimit-Reset` epoch time, then retry. |
| `500` | Unexpected platform error | Yes | Retry with exponential backoff (1s, 2s, 4s, 8s). Contact support if it persists. |

Successful but asynchronous: `202` means research was accepted. Save `requestIds` and poll or wait for a webhook.

## Error codes

| `code` | Status | Meaning | Retry? | What to do |
| - | - | - | - | - |
| `insufficientCredits` | 422 | Not enough credits for this search or research request. `data.additionalCreditsNeeded` says how many more you need, and can be fractional under custom pricing. | No | Lower the search `limit`, send fewer research records, or add credits. For contact research, `researchTypes: ["email"]` also costs less where your org allows it. Check `X-PublicAPI-Credits` or `GET /v2/credits`. |
| `missingApiAccess` | 422 | The organization has no active Public API license | No | Ask your Seamless admin or support to enable Public API access. |
| `rateLimitExceeded` | 429 | Too many requests to this endpoint in the current window | Yes | Wait until `X-RateLimit-Reset`. Limits are per endpoint, shared across your org. |
| `insufficientScope` | 403 | The OAuth connection lacks the scope the endpoint requires (`publicAPI.v1.all` on v1, `publicAPI.v2.all` on v2) | No | Re-run the OAuth flow with the right scope. |
| `noFeatureAccess` | 403 | A gated feature is not enabled for your organization (for example Public API v2, which is in beta) | No | Ask Seamless to enable the feature for your org. |
| `unsupportedConnection` | 403 | The OAuth connection is not associated with a registered client | No | Reconnect using a registered `client_id`. |
| `fullContactRequired` | 403 | Contact research sent one component in `researchTypes`, but your org's Contact Data is locked to Full Contact | No | Omit `researchTypes`, or send `["email", "phone"]`. |
| `component-disabled-for-org` | 403 | Contact research sent a component in `researchTypes` that your org disabled. `data.allowedResearchTypes` lists what you can send. | No | Remove that component, or ask your admin to enable it. |
| `variable-credits-disabled` | 403 | Contact research sent one component in `researchTypes`, but your account isn't on component-based pricing | No | Omit `researchTypes`, or send `["email", "phone"]`. |
| `invalidArguments` | 400 | A request field failed validation | No | The `message` names the field to fix. |

## Research poll statuses

Poll statuses arrive in a `200` response from `GET /contacts/research/poll` or `GET /companies/research/poll`. They are not HTTP errors.

| `status` | Meaning | Next step |
| - | - | - |
| `queued`, `researching` | Still working | Poll again in 2 to 5 seconds. |
| `done` | Finished | Read `contact` or `company`. |
| `duplicate`, `contact-already-researched` | Your org already researched this record | Read it from [My Contact Data](https://docs.seamless.ai/api-catalog/my-contact-data.md) or [My Company Data](https://docs.seamless.ai/api-catalog/my-company-data.md) instead of researching again. |
| `not found` | No match for the identifiers you sent | Try different identifiers, such as an email instead of name and company. |
| `missing` | The server has no record of that `requestId` (companies also report this while still pending) | Check the `requestId`; for companies, keep polling. |
| `No license or credits available` | Research was blocked by credits or license | Same fix as `insufficientCredits` or `missingApiAccess`. |
| `fullContactRequired`, `component-disabled-for-org`, `variable-credits-disabled` | Your org's Contact Data settings changed after the request was accepted, so the `researchTypes` you sent are no longer allowed. Nothing is charged. | Same fix as the matching 403 code above, then research again. |
| `error` | Research failed, for example a domain with no known company, or the request timed out | Check `message`. If it says the request timed out, submit the research again; otherwise don't retry the same input unchanged. |

## Endpoint-specific errors

| Endpoint | Status | When it happens |
| - | - | - |
| `GET /search/locations` | 400 | `q` is missing, `limit` is outside 1 to 100, or `types` has an unknown value |
| `POST /search/contacts`, `POST /search/companies` | 200 with `warnings` | A location value matched nothing. The search still runs; `warnings` suggests real spellings. |
| `POST /contacts`, `POST /companies` (v2) | 404 | A list, or every contact or company you sent, wasn't found |
| `POST /emails/send-bulk` (v2) | 400 | Invalid filters, no audience, an audience over the recipient limit (the `message` states the limit), or an invalid schedule |
| `POST /emails/send-bulk` (v2) | 409 / 422 | Same `Idempotency-Key` still in progress (409), or reused with a different body (422) |
| `POST /emails/{id}/send` (v2) | 400 / 404 | No sender email account could be resolved, or the draft can't be sent in its current status (400); the draft doesn't exist (404) |
| `POST /campaigns/{id}/steps/{stepId}/actions` (v2) | 400 | The action isn't allowed in the campaign's current status, such as pausing a draft |
| `POST /calls/log` (v2) | 404 | The contact wasn't found |

## Retry rules for agents and SDKs

**1. Retry only 429, 500, and 409**

Never retry `400`, `401`, `403`, `404`, or `422` without changing the request. The same request will fail the same way.

**2. Respect the reset time**

On `429`, read `X-RateLimit-Reset` (epoch seconds) and wait until then.

**3. Back off on 500**

Wait 1, 2, 4, then 8 seconds between attempts, and stop after 5 tries.

**4. Don't pay twice**

Before re-running research, check the poll status. `duplicate` means the data is already in your org for free.

## Related

* [Rate limits](https://docs.seamless.ai/core-concepts/rate-limits.md)
* [Credits](https://docs.seamless.ai/core-concepts/credits.md)
* [Troubleshooting](https://docs.seamless.ai/troubleshooting/authentication-and-request-failures.md)
* [Agent quickstart](https://docs.seamless.ai/api-catalog/agent-quickstart.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.