Error codes

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.

{
  "code": "insufficientCredits",
  "msg": "Insufficient credit amount.",
  "data": { "productCategory": "...", "additionalCreditsNeeded": 40 }
}

{
  "code": "rateLimitExceeded",
  "message": "Rate limit exceeded. Please wait and try again."
}

{
  "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.
`403`	OAuth token lacks the required scope (`insufficientScope`)	No	Re-authorize with scope `publicAPI.v1.all`. See 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.

`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 or 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

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.

Respect the reset time

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

Back off on 500

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

Don't pay twice

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

Catalog

Start here

Identity resolution

Search

Contact Search filters

Company Search filters

Research

My data

Platform

Coming soon

Error codes

Error body shapes

HTTP status codes

Error codes

Research poll statuses

Endpoint-specific errors

Retry rules for agents and SDKs

​Error body shapes

​HTTP status codes

​Error codes

​Research poll statuses

​Endpoint-specific errors

​Retry rules for agents and SDKs

​Related

Error body shapes

HTTP status codes

Error codes

Research poll statuses

Endpoint-specific errors

Retry rules for agents and SDKs

Related