Error handling

Handle Search1API authentication, payment, validation, rate-limit, and upstream errors.

Most API errors are JSON objects with ok: false and either error, message, or both. Validation errors also include an errors array.

{ "error": "Unauthorized: Invalid API Key", "ok": false }

Status codes

Status	Meaning	What to do
`400`	Malformed JSON or an invalid request value handled outside schema validation	Fix the request body and headers.
`401`	Invalid, revoked, or malformed bearer token	Check the key and the `Authorization` header.
`402`	Payment challenge or insufficient account credits	Add a bearer token, complete the payment flow, or add credits.
`404`	No search results, or a deepcrawl task was not found	Treat search `404` as zero results; verify a deepcrawl task ID before polling again.
`410`	A discontinued reasoning endpoint	Remove calls to `/v1/chat/completions` and `/v1/models`.
`422`	Request body failed schema validation	Read the `errors` array and fix the named fields.
`429`	More than 200 requests per minute on one key	Back off and retry.
`502`	An upstream service failed or timed out	Retry with backoff.
`500`	An unexpected gateway or service error	Retry; contact support if it persists.

Understand 402 responses

A paid endpoint can return 402 for two different reasons.

No bearer token

Search1API supports pay-per-request payment protocols. A request without a bearer token receives a payment challenge such as:

{
  "type": "https://paymentauth.org/problems/payment-required",
  "title": "Payment Required",
  "status": 402,
  "detail": "Payment is required (Search1API - Search API)."
}

If you intended to use account credits, add Authorization: Bearer YOUR_API_KEY. A bearer token that is present but invalid returns 401 instead.

When a request succeeds but its final cost is higher than the remaining balance, billing replaces the success response with 402 and an insufficient-credits message. Check the balance with GET /usage or add credits from the dashboard.

Fix validation errors

Search and news validation failures return 422 with an errors array:

{
  "ok": false,
  "message": "Query cannot be empty",
  "errors": [
    { "field": "query", "message": "Query cannot be empty", "code": "too_small" }
  ]
}

Common causes include an empty query, max_results below 1, or crawl_results greater than max_results. See the endpoint's API reference for its complete schema.

Treat a search 404 as zero results

/search and /news return 404 when the upstream search completes but finds no results. This is not a service outage, and the request is not charged. Broaden the query or remove narrow site and time filters.

Retry safely

Search and crawl requests have no write-side effects. Retry 429, 502, and transient 500 responses with exponential backoff and jitter. Do not retry 400, 401, 402, or 422 until you have changed the request or account state.

Failed requests are not charged. In a batch request, successful items are charged and failed items have a cost of zero.

If a 500 or 502 persists, contact sys@search1api.com with the endpoint, timestamp, and a redacted request body. Never send your API key.