biofrq

Usage limits

Each account has a 5-hour allowance and a weekly allowance. Both are shared by every project and every API key on the account, and both are measured in micro-credits, not in call counts. A call that costs more (for example identify) uses more of the allowance than one that costs less (for example detect).

Your plan sets the size of each allowance. Some plans have no allowance and are not limited this way. The dashboard's Usage limits card shows what you have used and when each allowance resets.

How a window works

  • A window starts at the first billable call after the previous window ended, and lasts 5 hours (or 7 days for the weekly window).
  • When the window ends, usage returns to zero. The next billable call starts a new window.
  • Calls inside the allowance are billed exactly as they are everywhere else. The allowance limits how much you can use in a window; it does not make calls free.
  • A call that fails (HTTP 4xx or 5xx) does not count against either window.

When an allowance is used up

The API answers with HTTP 429 and the code USAGE_LIMIT_REACHED. The response carries a Retry-After header (seconds until the window resets) and a details object:

json
{
  "ok": false,
  "requestId": "2c3f8b1a-9ed3-7c4a-8a1b-...",
  "action": "biofrq.detect",
  "errors": [
    {
      "code": "USAGE_LIMIT_REACHED",
      "message": "usage limit reached; retry after 7200 second(s)",
      "details": {
        "limit": "fiveHour",
        "resetsAt": "2026-10-08T17:30:00Z"
      }
    }
  ]
}
details.limitMeaning
fiveHourThe 5-hour allowance is used up.
weeklyThe weekly allowance is used up.
extraUsageCapExtra usage is on and this month's extra-usage cap is reached.

USAGE_LIMIT_REACHED is different from RATE_LIMITED. RATE_LIMITED means you are sending calls too fast; retrying after a moment succeeds. USAGE_LIMIT_REACHED means the allowance is used up until resetsAt; retrying sooner will not succeed.

Extra usage

Extra usage is off by default. When it is on, calls made after a window is used up are still served. Extra usage is billed at 1.5× the standard credit cost, and the monthly extra-usage cap you set counts that billed amount. For example, a call with a standard cost of 300 micro-credits counts 450 toward the cap. When the next call would take the month past the cap, calls return USAGE_LIMIT_REACHED with details.limit of extraUsageCap until 00:00 UTC on the first day of the next month.

Extra usage is not offered on every plan; where it is not offered, the setting is not shown. Only an account owner or admin can change extra usage. Turn it on from the Usage limits card on the dashboard and enter the monthly cap in the account's currency. A change takes effect within about a minute.

What's next