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 — 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:

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

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.