Concepts

Errors, Limits & Versioning

The operational contract

Errors

One envelope everywhere:

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

Every response carries live X-RateLimit-* headers — they, plus Retry-After on 429s, are the reference. Both per-minute limits and per-day quotas exist; on a 429, sleep exactly Retry-After seconds (it can be long when a daily quota is exhausted — quotas reset at 00:00 UTC), don’t retry-loop against the wall.

Client notes

Send a User-Agent header; our CDN blocks the default Python urllib agent (requests/httpx/Node defaults all pass).

Versioning

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

That’s the entire surface. If you encounter any issues, message support@sonicalpha.ai — we will get back to you asap.