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

The API returns three body shapes. Check for `code` first, then read `message` or `msg`.

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

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

```json All other errors theme={null}
{
  "message": "A human readable error message"
}
```

## HTTP status codes

| Status | Meaning | Retry? | What to do |
| - | - | - | - |
| `400` | Invalid request: a bad filter value, an out-of-range `limit`, or a missing required field | No | Fix the request. The `message` names the problem. |
| `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](/authentication/api-keys). |
| `403` | OAuth token lacks the required scope (`insufficientScope`) | No | Re-authorize with scope `publicAPI.v1.all`. See [OAuth](/authentication/oauth). |
| `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. | No | Lower the search `limit`, send fewer research records, or add credits. Check `X-PublicAPI-Credits` or `GET /v2/credits`. |
| `missingLicense` | 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 `publicAPI.v1.all` scope | No | Re-run the OAuth flow with the right scope. |

## 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](/api-catalog/my-contact-data) or [My Company Data](/api-catalog/my-company-data) instead of researching again. |
| `not found`, `missing` | No match for the identifiers you sent | Try different identifiers, such as an email instead of name and company. |
| `No license or credits available` | Research was blocked by credits or license | Same fix as `insufficientCredits` or `missingLicense`. |
| `error` | Research failed, for example a domain with no known company | Check `message`. 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, more than 500 contacts, 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) | 422 | No sender email account could be resolved, or the draft can't be sent in its current status |
| `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 and credits](/rate-limits-and-credits)
* [Troubleshooting](/troubleshoot-authentication-and-request-failures)
* [Agent quickstart](/api-catalog/agent-quickstart)


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