Home · Docs · Errors and limits

Errors and limits

What the FoxAPIs API answers when something is wrong, when a call costs credits and when it does not, and the limits that really exist. The status codes and sentences below are the ones the API itself sends; they were read from its source on 2026-11-22.

The rule that decides the charge

A call is charged only when it returns something. A call that fails, whether the cause is your input or the source, answers with an error status and the header X-Credits-Charged: 0, and the call is still written to your call log with its reason so you can see it. A call that returns some data and some errors is a partial success: it is charged as normal and the errors are listed in the body. A call that comes back empty is not charged. No results, no charge: a search that returns zero rows (a company, investor, paper, trial, patent or repository search) answers 200 with an empty list and X-Credits-Charged: 0, and a search is charged only when rows are returned.

Before this was fixed in November 2026, a failed extraction could answer 200 with the errors tucked inside the body and still cost credits. It no longer does: the status code is the first thing to check, and a 200 means you have data.

Status codes

StatusWhat it meansCharged?What to do
401The key is missing, wrong or switched off. The body says Invalid or inactive API key, or No customer found for this key when the key exists but its account does not.NoCheck the Authorization: Bearer header and the key on your account page. Keys start with fxp_.
402The account cannot pay for the call. Three codes in error.code: out_of_credits (no credits left), not_enough_credits (the call costs more credits than the balance holds; the sentence names both numbers) and subscription_inactive (the plan is not active).NoRead error.upgrade_url or the X-Upgrade-Url header: it is the page that opens the plan that lifts the limit. Top up or change plan, then repeat the call.
403The account service refused the key for a stated reason. Two reasons are limits on a free key, trial_expired and trial_calls_exhausted (the codes keep their old names), and come with the upgrade address; any other reason arrives as Access denied followed by the reason, also in the X-Deny-Reason header.NoOpen the upgrade address for a limit on a free key; for any other reason, write to support with the reason text.
404The source answered but has no such record, or the search matched nothing.NoCheck the identifier you sent: a username, repository, company number or id.
422The request itself is the problem: a field is missing, a value cannot be parsed, or it is not in the form the call expects (for example an address that does not start with https://).NoFix the input. Repeating the same request returns the same answer.
429The outside source is limiting requests right now. It is the source that says so, not a FoxAPIs counter on your key.NoWait and repeat; spread a batch over time.
503The source could not be reached, is not available yet, or the account service could not confirm your key. A key is never accepted when it cannot be checked: the service fails closed.NoRepeat after a short wait. Nothing was charged, so a retry cannot double-bill.

The API never answers 502 or 504 itself. Cloudflare sits in front of it and replaces those two with its own page, so a source that could not be reached is reported as 503 with a plain sentence instead.

What a 402 looks like

Plan limits keep the old detail text so existing callers work, and add an error object a program can read:

HTTP/1.1 402
X-Upgrade-Url: https://foxapis.com/checkout/?plan=builder

{
  "detail": "You have no credits left. To keep going, start the Builder plan here: https://foxapis.com/checkout/?plan=builder",
  "error": {
    "code": "out_of_credits",
    "message": "You have no credits left. ...",
    "upgrade_plan": "builder",
    "upgrade_url": "https://foxapis.com/checkout/?plan=builder"
  }
}

The plan named in upgrade_plan is the next one up from the caller's own: a caller on the free plan is pointed at Builder, a Builder caller at Production, and a Production or enterprise caller at the pricing page. A plan that is already paid cannot open a second checkout, so it is never sent to one.

Limits that exist

A retry loop that is safe

Because a failed call is never charged, retrying is safe for money. Retry 429 and 503 with a growing wait (a few seconds, then longer) and stop after a handful of tries. Do not retry 401, 402, 403, 404 or 422: the same request gets the same answer until you change the key, the balance or the input. For a 402, send the person or the job to the upgrade address instead of looping.

Start with 1,000 credits, no card. They arrive once you confirm your email and expire 90 days after they are added; credits you buy never expire.

Start with 1,000 credits

Related: How we calculate · Pricing · Docs · Status