Concepts

Errors & billing

Authentication, authorization and billing are three separate outcomes here, and nothing that fails to return usable data costs anything. Both of those are specified behaviour with tests behind them, not a courtesy.

1. 01
   validatefree

   Parameters are checked against the endpoint schema. A failure lists every bad path and never reaches a scraper.

2. 02
   preflightfree

   Missing credentials or proxies fail here, before the cache, so a misconfigured deployment fails identically whether or not something happens to be cached.

3. 03
   cachefree

   A hit inside your cache_max_age returns immediately with creditsCharged 0. A cache read failure degrades to a live fetch, never to an error.

4. 04
   chargemay charge

   Taken only after a miss, only when the endpoint costs more than zero, and only if the balance covers it. A balance can never go negative.

5. 05
   runfree

   The scraper executes. Async jobs run here too, with no request timeout above them.

6. 06
   settlefree

   Anything that threw is refunded in full. Anything empty is refunded in full. An endpoint may charge less than its listed price, never more.

7. 07
   cache writefree

   The result is stored for the next caller, unless your team has cache writes or retention turned off.

8. 08
   logfree

   Exactly one request log row per request, success or failure. A failed log write never fails the request.

{
  "success": false,
  "error": {
    "code": "upstream_blocked",
    "message": "The platform blocked this request. It was not charged.",
    "details": { }
  }
}

{
  "success": true,
  "data": { "items": [] },
  "meta": {
    "endpoint": "youtube.channel-videos",
    "creditsCharged": 0,
    "cached": false,
    "durationMs": 1104,
    "requestId": "req_01JB8Z..."
  }
}