> ## Documentation Index
> Fetch the complete documentation index at: https://docs.scan.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Errors and limits

> HTTP statuses, the error envelope, when to retry, and the sandbox allowance

Every Partner API v2 error includes stable `type` and `code` fields, a
`request_id`, and a documentation link. The legacy `error` string remains for
compatibility; validation failures can also include an `errors` list.

| Field               | Meaning                                                                                                            |
| ------------------- | ------------------------------------------------------------------------------------------------------------------ |
| `message`           | Same human-readable text as `error`                                                                                |
| `type`              | `authentication_error`, `validation_error`, `permission_error`, `not_found_error`, `rate_limit_error`, `api_error` |
| `code`              | Stable machine code (`unauthorized`, `sandbox_request_limit_reached`, …)                                           |
| `request_id`        | Attach this to every email to [api@scan.com](mailto:api@scan.com)                                                  |
| `documentation_url` | This page, anchored at the code                                                                                    |

The same id is in the `X-Request-Id` response header.

```json theme={"dark"}
{
  "error": "Referral not found",
  "message": "Referral not found",
  "type": "not_found_error",
  "code": "not_found",
  "request_id": "abc-123",
  "documentation_url": "https://docs.scan.com/guides/errors#not_found"
}
```

## Status codes

| Status        | Retry?                                  | Typical meaning                              |
| ------------- | --------------------------------------- | -------------------------------------------- |
| `400` / `422` | Never until you change the body         | Validation                                   |
| `401`         | Never until you rotate the token        | Missing, expired, or wrong-environment token |
| `403`         | Never until Scan enables the capability | Permission matrix                            |
| `404`         | Never for that id                       | Unknown resource                             |
| `429`         | After an extension                      | Sandbox cap exhausted                        |
| `5xx`         | Yes, with backoff                       | Internal or upstream failure                 |

Do not retry `4xx` except `429` after Scan extends the sandbox. Implement
exponential backoff on `429` and `5xx` even when you are not currently hitting a
production RPS cap.

## Common codes

### unauthorized

HTTP `401`. The `Authorization` header is missing, the token is not a valid
Partner API token, or you sent a sandbox token to production (or the reverse).

Rotate or re-issue the token from the matching environment and retry.

### api\_token\_expired

HTTP `401`. The 7-day sandbox window has elapsed.

Email [api@scan.com](mailto:api@scan.com) with the `request_id` for an extension,
or request a new sandbox.

### sandbox\_request\_limit\_reached

HTTP `429`. The 2,000-successful-request sandbox allowance is used up.

Email [api@scan.com](mailto:api@scan.com) with the `request_id` for an extension.
Access codes apply only when requesting the initial sandbox token.

### endpoint\_not\_enabled

HTTP `403`. The permission matrix does not grant this operation for the
authenticated group.

Ask Scan to enable the capability. Changing the request body will not unblock it.

### not\_found

HTTP `404`. The id does not exist, or it belongs to another group.

Use an id returned to this token. Do not retry the same id.

### unprocessable\_entity

HTTP `400` or `422`. The body failed validation (`errors` lists the fields).

Fix the payload using the `errors` array and retry. Failed `4xx` requests do not
count toward the sandbox allowance.

### internal\_error

HTTP `5xx`. Scan or an upstream dependency failed.

Retry with exponential backoff. Include the `request_id` if it persists.

## Limits

Production Partner API tokens do not have an application-level RPS cap in this
API today. Scan may introduce production rate limits; treat `429` as retryable
with backoff regardless of environment. Today, a sandbox `429` means its request
allowance has been used up; it is not a general production rate limit.

The self-serve sandbox allows **2,000 successful requests** or **7 days**,
whichever comes first. Requests that return `4xx` or `5xx` do not count toward
the allowance, so correcting a validation error does not use it up.

`GET` list endpoints that return `200` do count.

When the cap is used up:

```json theme={"dark"}
{
  "error": "Sandbox request limit reached",
  "message": "Sandbox request limit reached",
  "type": "rate_limit_error",
  "code": "sandbox_request_limit_reached",
  "request_id": "abc-123",
  "documentation_url": "https://docs.scan.com/guides/errors#sandbox_request_limit_reached"
}
```

Contact [api@scan.com](mailto:api@scan.com) with the `request_id` for an
extension. Access codes are accepted only on the initial **Get API keys**
request. See [Authentication](/authentication).