Errors

Errors are JSON with a human message and, where it matters, a stable machine code:

{ "error": "This data requires a Pro subscription.", "code": "upgrade_required" }

Status	Code	Meaning	Do
400	—	Invalid parameter	Fix the request; the message says which parameter. An unknown accounting `basis` returns the company’s `accounting_bases[]` to choose from.
401	`unauthenticated`	Key missing, revoked, malformed — or an expired session token	Supply a valid key. Don’t retry in a loop.
402	`upgrade_required`	Pro-only surface	Upgrade, or tell your user.
404	—	Unknown company, country, symbol, period or accession	Re-resolve via `/search`.
409	`key_limit`	Too many active keys	Revoke one first.
415	—	A filing package with nothing renderable (XBRL-only)	Read the facts through `/financials` and `/fact-source` instead.
429	`rate_limited`	Per-minute or per-day ceiling	Sleep `Retry-After` seconds.
429	`quota_exceeded`	Monthly quota spent	Wait for `resets_at`; the body carries `sales_email` for more volume.
5xx	—	Server fault	Retry with backoff; report if persistent.

Message strings are for humans and may change; codes are the contract.