API documentation/v2

Errors

Error responses include the shared billing fields and the error-specific fields below. Codes are stable and safe to branch on.

Error envelope

Read retryable and billed from the response; don’t infer their values from the HTTP status.

Field	Type	Description
`ok`	`false`	Always false.
`error`	`string`	Stable public error code.
`message`	`string`	Explanation of the problem and how to address it. Wording may change; use `error` and `retryable` for application logic.
`doc_url`	`string`	Link to the relevant documentation page.
`retryable`	`boolean`	Retry only when true.

For invalid_request, message explains the first validation problem encountered. Follow doc_url for the relevant request, pagination or error guidance.

JSON

{
  "ok": false,
  "error": "invalid_request",
  "message": "The URL must include a non-empty 'q' parameter.",
  "doc_url": "https://reserp.ai/docs/search",
  "retryable": false,
  "billed": false,
  "billing_source": null
}

Error codes

Status / errorWhat to do

400invalid_request

Fix the request before sending it again.

401authentication_failed

Check the bearer API key.

402free_allowance_exhausted

Add balance or wait for the next UTC month.

403request_not_allowed

The account or request is not permitted.

429rate_limited

Use Retry-After before retrying.

500internal_error

An unexpected service error occurred.

502search_failed

The search could not be completed.

503service_unavailable

The service is temporarily unavailable.

Retry only when retryable is true. For 429, wait for the number of seconds in Retry-After. For other retryable errors, use exponential backoff with jitter.