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

# Errors

> The errors the AlphaYou API returns, what they mean and what to do.

Errors come back as JSON with an `error` code and a plain-English `message`.

| Status | `error` | What it means | What to do |
| - | - | - | - |
| `400` | `invalid_ticker`, `invalid_cik`, `invalid_cursor`, `invalid_side` and similar | An input is wrong. The `message` says which | Fix the input. For `invalid_cursor`, use a `nextCursor` from an earlier reply of the same call |
| `401` | `unauthorized` | No key was sent, or the key is not recognised | Send `x-api-key` or `Authorization: Bearer`. Check the key |
| `401` | `key_revoked` | The key was revoked | Make a new key at [alphayou.net/developers](https://alphayou.net/developers) |
| `403` | `tier_required` | The dataset needs Pro and your key is on Free | Pick a Free dataset, or upgrade on the [pricing page](https://alphayou.net/pricing) |
| `403` | `key_suspended` | The key has been suspended | Write to [info@alphayou.net](mailto:info@alphayou.net) |
| `404` | | The address is not one a key may call, or a stock symbol has no SEC-registered company | Check the address and the symbol |
| `429` | `rate_limited` | You called too fast, or used up a budget | Wait `Retry-After` seconds, then try again |
| `503` | | The request budget could not be checked right now | Wait `Retry-After` seconds, then try again |

A bad input returns a `400` with an `error` such as `invalid_ticker` and a `message` that names the problem. The API gives a clear coverage message instead of made-up data.

## Examples

### 401, key missing

```json theme={null}
{
  "error": "unauthorized",
  "message": "Send your AlphaYou API key as \"x-api-key: ay_...\" or \"Authorization: Bearer ay_...\". Get a free key at https://alphayou.net/developers."
}
```

### 401, key not recognised

```json theme={null}
{
  "error": "unauthorized",
  "message": "That API key is not recognised. Create one at https://alphayou.net/developers."
}
```

### 403, plan too low

```json theme={null}
{
  "error": "tier_required",
  "message": "alphayou_fund_holdings requires the Pro plan; this key is on the Free plan. See https://alphayou.net/pricing.",
  "tool": "alphayou_fund_holdings",
  "requiredPlan": "pro",
  "yourPlan": "free"
}
```

The response may carry extra fields. Read `error` first.

### 429, too fast

A `429` carries a `Retry-After` header with the seconds to wait. The body has `error` set to `rate_limited` and a `scope` that says which budget ran out:

| `scope` | Meaning |
| - | - |
| `minute` | You went over the per-minute limit. This does not use up your day |
| `day` | You used your daily allowance |
| `account` | The allowance shared by all of an account's keys ran out |
| `concurrency` | Too many calls were running at the same time |

## An empty result is not an error

A `200` with `count` of 0 means the record is not on file. It does not mean nobody filed. For example, an empty insider-trades list means no open-market trade is on file for that search. Read `coverage` in the response for what the dataset includes and leaves out.

## Retry the safe way

* Stop a request that hangs. 20 seconds is a sensible timeout.
* After a `429`, wait `Retry-After` seconds. Do not retry in a tight loop.
* After a timeout, wait a few seconds and try once more. If it keeps failing, write to [info@alphayou.net](mailto:info@alphayou.net) with the time and the address you called.
* Do not retry a `400`, `401`, `403` or `404`. The same call will fail the same way.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.