402 payment loop
Your agent runs on the free tier and hands its human a payment link when it runs out. No signup step in between.
- Call any endpoint with no key. Read X-Credits-Remaining to see how many free requests are left today.
- When the allowance or a key's credits run out, the API answers 402 with error "keyless_limit" or "insufficient_credits", an X-Payment-URL header and a JSON body with action and packs.
- Show your human action.prompt_to_user and stop retrying. Every link in it (action.url, packs[].checkout_url) opens Stripe Checkout in one click.
- After payment the success page shows the key and copies it to the clipboard. Retry with Authorization: Bearer <key>.
HTTP 402 body
{
"error": "keyless_limit",
"message": "Daily free tier limit (25 requests) reached. Reload 15,000 searches for $15.",
"checkout_url": "https://contextfetch.dev/#buy",
"pricing": {
"pack_size": 15000,
"price_usd": 15,
"unit_cost_usd": 0.001
},
"packs": [
{
"id": "instant",
"name": "Instant",
"credits": 15000,
"price_usd": 15,
"cost_per_1k": 1,
"recommended": false,
"checkout_url": "https://api.contextfetch.dev/buy/instant"
},
{
"id": "builder",
"name": "Builder",
"credits": 60000,
"price_usd": 50,
"cost_per_1k": 0.83,
"recommended": true,
"checkout_url": "https://api.contextfetch.dev/buy/builder"
},
{
"id": "scale",
"name": "Scale",
"credits": 200000,
"price_usd": 150,
"cost_per_1k": 0.75,
"recommended": false,
"checkout_url": "https://api.contextfetch.dev/buy/scale"
}
],
"action": {
"type": "payment_link",
"url": "https://api.contextfetch.dev/buy/instant",
"prompt_to_user": "ContextFetch credits ran out. Reload 15,000 searches for $15: https://api.contextfetch.dev/buy/instant"
}
}| Header | Meaning |
|---|---|
| X-Payment-URL | On 402: https://api.contextfetch.dev/buy/instant, one click to Stripe Checkout (card, Apple Pay, Google Pay). |
| X-Credits-Remaining | On every billable response: free requests left today for keyless calls, credits left for a paid key. |
On /tavily/* the same condition returns 432 with {"detail": {"error": "..."}} and the same X-Payment-URL header. checkout_url (https://contextfetch.dev/#buy) stays in the body for older clients.