Error Handling

Every error answers JSON with success: false and a human-readable message, and almost every one adds a stable machine-readable name for the failure. Branch on that name and the status, not on message, which may be reworded. The name is in code; on a few errors, marked † below, it is in errorCode instead, so read code and fall back to errorCode.

Error Response Format#

{  "success": false,  "code": "AT_CAPACITY",  "message": "Google SERP is at capacity. Retry in 60s — immediate retries will be refused.",  "retryable": true,  "retryAfterSec": 60}

• retryable says whether the same request can succeed later. When it is true, wait Retry-After (header) or retryAfterSec (body) before retrying.
• Validation errors add an errors array of { field, message }:

{  "success": false,  "code": "VALIDATION_ERROR",  "message": "Query validation failed: \"q\" is required",  "errors": [{ "field": "q", "message": "\"q\" is required" }]}

• Insufficient-credit errors (402) add details:

{  "success": false,  "error": "Insufficient credits",  "code": "INSUFFICIENT_CREDITS",  "details": { "required": 5, "available": 2, "shortfall": 3 },  "message": "This request requires 5 credit(s), but you only have 2 credit(s) available. Please purchase more credits to continue.",  "topUpUrl": "https://dashboard.searlo.tech/credits?tab=buy&source=api_402"}

Codes#

Every status and code the API answers, in one table. A call that answers with one of them is never charged: it releases the credits it held, and the 429s for rate limits and searches in flight are refused before any credit is reserved. A 200 that finds nothing (an empty list) is not charged either. The one exception is a failed row inside a 200 POST /rankings/batch, which is billed with the batch (see Refunds). † marks a name carried in errorCode.

The rate-limit 429s carry a numeric code (4201, 4202, 4203); every other code is a string. Errors are JSON on every status, a 5xx included: we answer 503 rather than 502 or 504, which the network in front of us would replace with its own HTML page. Every retryable 503 carries Retry-After.

Idempotency keys#

Send X-Idempotency-Key (or Idempotency-Key), up to 255 characters, to make a retry of a paid call safe. Within an hour of the first use:

• the same key with the same request returns the stored response, marked Idempotent-Replayed: true, without running or charging again;
• the same key with a different request is 422 IDEMPOTENCY_KEY_REUSED, not charged;
• the same key while the first request is still running is 409 IDEMPOTENCY_REQUEST_IN_PROGRESS: retry shortly (Retry-After: 2).

A request that failed is not kept, so you can retry it with the same key. A key longer than 255 characters is 400 INVALID_IDEMPOTENCY_KEY. Async tasks take their own idempotencyKey in the body (Async Tasks).

Refunds#

A call that fails is not charged: any response with status 400 or above, or with success: false, releases the credits it reserved. An answer with no results (an empty organic, news, videos, images, places, reviews or shopping list) is not charged either, and the body's credits always equals the X-Credits-Deducted header. In POST /search/batch and POST /serp/batch a failed or empty row costs nothing; a row inside a 200 POST /rankings/batch is billed like the rest of that batch (read each row's success and retryable). A failed async task is refunded.

Retrying#

Retry only what says it can succeed later: 429s, and 5xx responses with retryable: true. Wait Retry-After when it is present, and back off otherwise (for example 2, 5, then 10 seconds). Because failures are refunded, a retry never bills twice.

// Retries what says it can succeed later, waiting Retry-After when given.// Failed calls are refunded, so a retry never bills twice.async function searlo(path, params = {}, { retries = 3 } = {}) {  const url = new URL(`https://api.searlo.tech/api/v1${path}`);  Object.entries(params).forEach(([k, v]) => url.searchParams.set(k, v));   for (let attempt = 0; ; attempt++) {    const res = await fetch(url, { headers: { "x-api-key": process.env.SEARLO_API_KEY } });    const body = await res.json();    if (res.ok && body.success !== false) return body;     const retryable = res.status === 429 || (res.status >= 500 && body.retryable !== false);    if (!retryable || attempt >= retries) {      const err = new Error(body.message || `HTTP ${res.status}`);      err.status = res.status;      err.code = body.code; // e.g. CITY_LOCATION_UNAVAILABLE, INSUFFICIENT_CREDITS      throw err;    }    const wait = Number(res.headers.get("retry-after")) || [2, 5, 10][attempt] || 10;    await new Promise(r => setTimeout(r, wait * 1000));  }}

import osimport timeimport requests class SearloError(Exception):    def __init__(self, status, code, message):        super().__init__(message)        self.status, self.code = status, code def searlo(path, params=None, retries=3):    url = f"https://api.searlo.tech/api/v1{path}"    headers = {"x-api-key": os.environ["SEARLO_API_KEY"]}    for attempt in range(retries + 1):        r = requests.get(url, params=params, headers=headers, timeout=120)        body = r.json()        if r.ok and body.get("success") is not False:            return body        retryable = r.status_code == 429 or (r.status_code >= 500 and body.get("retryable") is not False)        if not retryable or attempt == retries:            raise SearloError(r.status_code, body.get("code"), body.get("message", "request failed"))        time.sleep(float(r.headers.get("Retry-After") or [2, 5, 10][min(attempt, 2)]))