API HTTP status codes

HTTP status codes tell you whether your request succeeded, failed authentication, hit a rate limit, or needs a corrected payload. This page covers the status codes you are most likely to see when calling the Seamless v1 REST API.

Poll status values such as done, error, or duplicate are not HTTP errors — they appear in a 200 response body when you call a poll endpoint. See Authenticate and make your first request for poll status meanings.

Status code reference

HTTP status	Meaning	Typical cause	What to do
400	Bad request	Invalid or missing parameters in the request body or query string	Fix the request payload and compare with the endpoint reference
401	Unauthorized	Missing, invalid, expired, or revoked API key or access token	Confirm the `Token` or `Authorization: Bearer` header; rotate or refresh credentials — see API keys or OAuth
403	Forbidden	OAuth connection lacks required permission (`insufficientScope`)	Re-authorize with scope `publicAPI.v1.all` — see OAuth
404	Not found	Wrong URL or path	Confirm the base URL `https://api.seamless.ai/api/client/v1/...` and endpoint path
422	Unprocessable	Insufficient credits or missing license — see 422 details below	Fix credits or license — see Rate limits and credits
429	Too many requests	Rate limit exceeded (`rateLimitExceeded`)	Wait until `X-RateLimit-Reset` — see Rate limits and credits
500	Server error	Unexpected platform error	Retry with backoff; contact support if it persists
202	Accepted	Research request queued successfully (not an error)	Save `requestIds` and poll or use webhooks

422: insufficient credits vs missing license

Both problems return HTTP 422, but the code field in the JSON body tells you which one applies:

`code`	Meaning	What to do
`insufficientCredits`	Your account does not have enough research credits for this request	Check Settings → Billing in the Seamless app or the `X-PublicAPI-Credits` response header; reduce batch size or add credits
`missingLicense`	Your account does not have an active Public API license	Contact your Seamless administrator or support to enable Public API access

Example — insufficient credits:

{
  "code": "insufficientCredits",
  "msg": "Insufficient credit amount."
}

Example — missing license:

{
  "code": "missingLicense",
  "msg": "Public API requires an active license."
}

429: rate limit exceeded

When you exceed your organization’s rate limit, the API returns 429 with a JSON body similar to:

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

Read X-RateLimit-Reset from the response headers and wait until that time before retrying the same endpoint.

Rate limits and credits — limits, headers, and credit balance
Troubleshoot authentication and requests — workflow, identifier, and webhook issues
API keys — authenticate with the Token header
OAuth — authenticate with Bearer tokens

Get Started

Core concepts

Use cases

Workflows

Guides

Troubleshooting

API HTTP status codes

Status code reference

422: insufficient credits vs missing license

429: rate limit exceeded

​Status code reference

​422: insufficient credits vs missing license

​429: rate limit exceeded

​Related

Status code reference

422: insufficient credits vs missing license

429: rate limit exceeded

Related