Errors

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

Status	`error`	What it means	What to do
`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
`403`	`tier_required`	The dataset needs Pro and your key is on Free	Pick a Free dataset, or upgrade on the pricing page
`403`	`key_suspended`	The key has been suspended	Write to 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

Bad inputs, such as an unsupported value, return a validation error that names the problem. The API gives a clear coverage message instead of made-up data.

Examples

401, key missing

{
  "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

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

403, plan too low

{
  "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 with the time and the address you called.
Do not retry a 401, 403, 404 or validation error. The same call will fail the same way.

Get started

Use the API

Endpoint reference

Examples

401, key missing

401, key not recognised

403, plan too low

429, too fast

An empty result is not an error

Retry the safe way

​Examples

​401, key missing

​401, key not recognised

​403, plan too low

​429, too fast

​An empty result is not an error

​Retry the safe way

Examples

401, key missing

401, key not recognised

403, plan too low

429, too fast

An empty result is not an error

Retry the safe way