API reference
Errors
Every failure has a status code that says what to do about it. Nothing is disguised as an empty result.
Wiring this up with a coding agent? Point it at agents.md or openapi.json rather than at these pages. Both are generated from the code that serves the requests, so neither can describe an endpoint that no longer exists.
Status codes
| Status | When |
|---|---|
| 400 | Malformed request. details carries the field errors. Fail loud; this is a bug in the caller, not an empty result. |
| 401 | Missing, unknown, or revoked key. |
| 403 | Valid key, insufficient scope. |
| 429 | Rate limit or quota. Rate limits carry retry-after. |
| 502 | The search could not be run, or nothing could be extracted. |
| 503 | A required capability is not configured. |
A missing capability returns 503 and names it. A response that looks successful while leaving out the thing you asked for sends you debugging the wrong layer.
An empty list is not an error
A 200 with an empty results array means the search ran and
found nothing. It is never how a failure reaches you, which is what makes it safe to
treat as an answer rather than as something to retry. The
search reference sets out the four cases side by side.