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

# API HTTP status codes

> Reference for HTTP status codes returned by the Seamless v1 API, including authentication, rate limit, credit, and license errors.

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.

<Note>
  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](/authenticate-and-make-your-first-request) for poll status meanings.
</Note>

## 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](/authentication/api-keys) or [OAuth](/authentication/oauth) |
| **403**     | Forbidden         | OAuth connection lacks required permission (`insufficientScope`)                                                | Re-authorize with scope `publicAPI.v1.all` — see [OAuth](/authentication/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](#422-insufficient-credits-vs-missing-license) below | Fix credits or license — see [Rate limits and credits](/rate-limits-and-credits)                                                                                  |
| **429**     | Too many requests | Rate limit exceeded (`rateLimitExceeded`)                                                                       | Wait until `X-RateLimit-Reset` — see [Rate limits and credits](/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:

```json theme={null}
{
  "code": "insufficientCredits",
  "msg": "Insufficient credit amount."
}
```

Example — missing license:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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.

## Related

* [Rate limits and credits](/rate-limits-and-credits) — limits, headers, and credit balance
* [Troubleshoot authentication and requests](/troubleshoot-authentication-and-request-failures) — workflow, identifier, and webhook issues
* [API keys](/authentication/api-keys) — authenticate with the `Token` header
* [OAuth](/authentication/oauth) — authenticate with Bearer tokens