Usage and quotas

Calls with a fapi_live_ key count toward your monthly quota. Calls with a fapi_test_ key never count.

What counts

Response	Counted
200 (including valid: false from /validate)	Yes
404 not_found (the code does not exist; that is an answer)	Yes
400 invalid_request (a malformed request)	No
401, 403 plan_required, 429 quota_exceeded	No
Any 5xx	No

A batch counts one call per request in it.

These never count, whatever the response, and keep working when your monthly calls run out:

• GET /autocomplete
• Adding and removing watchlist codes (PUT and DELETE /watchlists/{code})

Where calls come from

The quota period is the calendar month in UTC. Each call is taken, in order, from:

1. Your plan’s monthly calls (Free 20, Pro 200).
2. Call packs you have bought (for example 100 calls for $25). Pack calls do not expire at the end of the month.
3. Metered overage, if you turned it on in the portal, up to the monthly cap you set. Overage calls are billed per call on your next invoice.

When all three are used up, the API answers 429 with the code quota_exceeded and links to buy a pack, turn on overage or upgrade. Nothing is counted for a 429.

{
  "error": {
    "code": "quota_exceeded",
    "message": "You have used all the calls your plan and call packs include this month. Buy a call pack, turn on metered overage, or upgrade to keep going.",
    "links": {
      "docs": "https://docs.firmsapi.com/api/errors/#quota_exceeded",
      "buy_pack": "https://app.firmsapi.com/billing?buy=pack",
      "billing": "https://app.firmsapi.com/billing",
      "upgrade": "https://app.firmsapi.com/billing?upgrade=pro"
    }
  },
  "meta": { "data_as_of": null, "source": null, "mode": "live", "request_id": "…" }
}

Packs are never charged automatically. When your balance runs low, buy another pack in the portal; or turn on metered overage if you want calls to keep working without doing anything.

Quota headers

Counted calls return your plan quota for the month:

Header	Meaning
x-quota-limit	Calls your plan includes this month
x-quota-remaining	Plan calls left this month (packs and overage are not included)