Skip to main content
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.

HTTP status codes

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

Error codes

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.

Endpoint-specific errors

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.