API errors

When a request fails because of invalid input, missing or invalid credentials, missing resources, credit limits, or server faults, the API returns JSON with an HTTP status that matches the failure category.

Most error responses use a flat JSON error envelope (status, message, optional code). POST /v2/search and other billable routes may return 402 with structured credit fields when balance is insufficient.

Error response

Property	Type	Description
`status`	string	Typically `error`.
`message`	string	Human-readable explanation. Safe to show in UI.
`code`	string	Optional machine-oriented identifier when present.

HTTP status reference

Status	Meaning
400	Request or parameters failed validation or business rules.
401	Missing or invalid API key (`X-API-Key`).
402	Insufficient credits for a paid operation.
403	Authenticated but not allowed to perform the action.
404	Resource does not exist for the authenticated context.
500	Unexpected server failure.

For credit costs, see Credits and tiers.

Insufficient credits (402)

Billable routes such as POST /v2/search return 402 when the account cannot cover the request. The body may include fields such as required and available credits to drive upgrade UX.

Client guidance

Branch on HTTP status for control flow (retry 500 only with backoff; do not retry 400, 401, 402, 403, or 404 without changing the request).
Display message to people; do not parse it for logic.
Use code when present for machine branching, but expect it to be absent on some routes.
Streaming (chat=true) responses use application/x-ndjson; successful frames use search, chunk, and done. Treat other line types or transport errors as stream failures.