Handle errors and retries

Send a bad call and see what an error looks like. No key needed.

curl -X POST https://api.stophy.dev/v1/google/search \
  -H "content-type: application/json" \
  -d '{"query":"bun runtime","foo":1}'

Response

{
  "error": {
    "code": "invalidRequest",
    "message": "Unknown field `foo`. Fields: query, country, language, includeDomains, excludeDomains, time, safeSearch, page, scrapeResults, scrapeLimit",
    "retryable": false,
    "requestId": "fb79d36c-6041-4e7f-a934-ed72fef872c2"
  },
  "success": false
}

Every error has this shape, and a failed call costs nothing. Read retryable before you do anything else.

Decide what to do

When	Do this
`retryable` is `false`	Don’t retry. Fix the request, or read the message.
`retryAfterSeconds` is set	Wait that many seconds, then retry. The `Retry-After` header has the same value.
`retryable` is `true` with no wait	Back off: 0.5 s, then 1 s, then 2 s.
Still failing after a few tries	Stop, and log the `requestId`.

Every code is listed in Errors.

A retry loop

async function call(id: string, input: object, attempts = 3) {
  for (let attempt = 0; ; attempt++) {
    const response = await fetch(`https://api.stophy.dev/v1/${id.replaceAll(".", "/")}`, {
      method: "POST",
      headers: {
        authorization: `Bearer ${process.env.STOPHY_API_KEY}`,
        "content-type": "application/json",
      },
      body: JSON.stringify(input),
      signal: AbortSignal.timeout(30_000),
    });
    const body = await response.json();
    if (body.success) return body.data;
    if (!body.error.retryable || attempt + 1 >= attempts) {
      throw new Error(`${body.error.code}: ${body.error.message} (${body.error.requestId})`);
    }
    const seconds = body.error.retryAfterSeconds ?? 0.5 * 2 ** attempt;
    await new Promise((resolve) => setTimeout(resolve, seconds * 1000));
  }
}

import os
import time

import requests


def call(endpoint_id, payload, attempts=3):
    for attempt in range(attempts):
        response = requests.post(
            f"https://api.stophy.dev/v1/{endpoint_id.replace('.', '/')}",
            headers={"Authorization": f"Bearer {os.environ['STOPHY_API_KEY']}"},
            json=payload,
            timeout=30,
        )
        body = response.json()
        if body["success"]:
            return body["data"]
        error = body["error"]
        if not error["retryable"] or attempt + 1 >= attempts:
            raise RuntimeError(f"{error['code']}: {error['message']} ({error['requestId']})")
        time.sleep(error.get("retryAfterSeconds", 0.5 * 2**attempt))

Common cases

401 unauthorized means the key is missing or wrong. Send Authorization: Bearer <key>.
402 insufficientCredits means your balance is too low. The error says how many credits the call needs and how many you have. Add credits and try again.
429 rateLimited or tooManyInFlight means you are over your rate limits. Wait, then retry.
400 invalidRequest means the input is not valid. The message names the field. Check the endpoint’s input in the API reference.
404 notFound means the thing you asked for does not exist. Don’t retry.

Timeouts

Every call answers or fails within 25 seconds. Set your client timeout a little above that, such as 30 seconds.

Get started

What you can get

Guides

Plans and billing

Handle errors and retries

Decide what to do

A retry loop

Common cases

Timeouts

​Decide what to do

​A retry loop

​Common cases

​Timeouts

Decide what to do

A retry loop

Common cases

Timeouts