Skip to main content
Two independent things gate an API call, and they fail differently:
There is no monthly request quota. Earlier versions of these docs described a “1,000 requests per 30 days” allowance per key. That model has been retired. Usage is metered in US dollars against your organization’s credit balance, and a cheap call and an expensive one no longer count the same.One exception: a legacy person-bound key — an older jnk_ key tied to a user account rather than to a tenant — is still counted against a per-user allowance of 1,000 requests per 30 days, on top of the credit above. Every tenant-scoped key (jnk_t_…), which is what the dashboard issues for server-to-server use, is metered in dollars only. The prefix is the tell: jnk_t_ is tenant-scoped, a bare jnk_ is the older person-bound kind.

​
Credit

Credit belongs to the organization, not to a key. Every tenant and every API key under the organization draws on one balance, so spreading work across several keys does not give you more to spend. Calls are priced individually — a live provider search costs more than a cache read — so your balance moves by the value of what you actually called, not by a request count. The per-call price and this cycle’s usage are itemised on the Billing page.

​
Included usage

Every plan includes an amount of usage each billing cycle. On the Free plan that is $5.00 per month, with no fee and no card required.
Included usage does not roll over. The grant covers one billing cycle and expires when that cycle ends. An unused 5doesnotbecome5 does not become 10 next month — every cycle starts at the plan’s amount, whatever you did or did not spend before it.
The dashboard shows your balance and the date the cycle resets.

​
Topping up

You can buy extra credit from the dashboard at any time, on any plan. Purchased credit is separate from the monthly grant and is not cleared at the cycle boundary. Included usage is always spent before purchased credit, so topping up mid-cycle never burns the free allowance you still had.

​
Running out

When a call costs more than the organization’s remaining balance, it is refused with 402 Payment Required:
The message names what the call cost, what you had, and where to top up.
Do not retry a 402. It is deliberately not a 429. Retrying never fills a wallet, and an agent that treats this as backpressure will back off and spin quietly instead of telling you to add credit. Surface it to a human, or top up.
Your key stays active through all of this — a 402 is a billing state, not a credential problem. Nothing needs rotating, and the same key resumes working the moment the balance covers the next call.

​
Rate limits

Rate limiting is a separate axis from credit. Credit caps total consumption, not burst rate, so an organization with plenty of credit can still be throttled for calling too fast. The ceiling is a sustained requests-per-second rate with a short burst allowance. The number comes from your organization’s plan, or from an enterprise contract carrying its own negotiated one — but it is applied per tenant, so each tenant gets its own bucket. That is the opposite of how credit works, and the difference is deliberate: credit is one shared organization balance, so splitting work across tenants never buys you more to spend, while separate throughput buckets keep one busy tenant from starving another. Over the ceiling, you get 429 and should back off:
Honour the Retry-After header when one is present; otherwise retry with exponential backoff. Unlike a 402, a 429 is worth retrying.
Per-plan throughput ceilings are set per environment and per contract, so they are not printed here — a number in a docs page would drift out of date. To find the ceiling on your plan, or to raise it, email dev@gojinko.com.

​
See also