Handle errors and retries

Every error has the same shape, and failed calls cost nothing.

{
  "success": false,
  "error": {
    "code": "sourceTimeout",
    "message": "The source took too long to answer. Try again.",
    "retryable": true,
    "requestId": "..."
  }
}

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`.

The full list of codes is 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: the key is missing or wrong. Check the Authorization: Bearer <key> header.
402 insufficientCredits: your balance is too low. Nothing was charged, and the error says how many credits the call needs and how many you have. Top up and try again.
429 rateLimited or tooManyInFlight: you are over your rate limits. Wait, then retry.
400 invalidRequest: the input is not valid. The message names the field, or repeats the source’s own complaint. Check the endpoint’s input in the API reference.
404 notFound: the thing you asked for does not exist. The message is the source’s own, such as YouTube says: This video is unavailable. Don’t retry.

Timeouts

Every call answers or fails within 25 seconds. Set your client timeout a little above that, for example 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