> For clean Markdown of any page, append .md to the page URL. For a complete documentation index, see https://docs.sonicalpha.ai/llms.txt. For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.sonicalpha.ai/_mcp/server. For SDK generation or contract validation, use the authoritative OpenAPI spec at https://api.sonicalpha.ai/openapi.json — this docs domain's /openapi.json is a regenerated copy that can differ in auth modeling and strictness annotations.

# Errors, Limits & Versioning

## Authentication

Pass your key as `Authorization: Bearer sk_...` — the documented scheme,
and what generated clients use. The `X-API-Key: sk_...` header is also
accepted at runtime as a compatibility alternative; it is deliberately
not modeled in the OpenAPI spec, so tooling sees one auth path.

## Machine-readable spec

The authoritative OpenAPI 3.1 document is
[`api.sonicalpha.ai/openapi.json`](https://api.sonicalpha.ai/openapi.json)
— use it for SDK generation and contract validation. This docs site also
serves a `/openapi.json`, but it is regenerated from the docs platform's
internal model and can differ from the authoritative spec (auth modeled
as a raw header instead of a bearer scheme; `additionalProperties`,
response headers, and examples omitted).

## Errors

One envelope everywhere:

```json
{"error": {"type": "invalid_request_error", "message": "query: must be at least 8 characters"}}
```

Standard HTTP codes; 429s include `Retry-After`. Unknown or outdated
parameter names are a 400 that names the supported ones — nothing is
silently ignored.

## Rate limits

Default limits per key:

| Endpoints                               | Per minute | Per day |
| --------------------------------------- | ---------- | ------- |
| `/podcasts*`, `/episodes*`              | 120        | 10,000  |
| `/insights/search`, `/insights/{id}`    | 60         | 2,000   |
| `/insights/ask`, `/insights/ask/stream` | 10         | 100     |

Every authenticated response carries live `X-RateLimit-*` headers for the
per-minute window — they, plus `Retry-After` on 429s, are the reference.
The daily quota has no header; it surfaces as a 429 with a long
`Retry-After` (quotas reset at 00:00 UTC). On any 429, sleep exactly
`Retry-After` seconds — don't retry-loop against the wall. Higher limits
are available; get in touch.

## Versioning

The surface is `/v1`; fields are added, never renamed or removed.