Guides

Credits & rate limits

Credits are the billing unit. One credit is charged per external provider that answered. Cache hits, no-answer lookups, and reporting calls are free.

What a call costs

Call	Cost
`POST /v1/validate`, uncached	1 credit per provider that answered. A fan-out answered by 3 providers costs 3; if no provider answers, it costs 0.
`POST /v1/autocomplete`, uncached	Same rule: 1 credit per answering provider per call, or 0 when no provider answers.
`POST /v1/widget/autocomplete`, uncached	Same rule, billed to the account that owns the token's project.
Any response with `"cached": true`	0 credits.
`GET /v1/usage`	0 credits. Reporting never writes to the ledger, but the endpoint still returns 429 after the account exhausts its credits.
`GET /healthz`	0 credits.
`POST /demo/validate`	0 credits (IP rate limited instead).

Your routing strategy therefore drives cost directly. Cost Efficient stops at the first sufficient answer and usually costs 1 credit; Most Accurate queries every selected provider and costs one credit per provider that responded. See routing strategies.

No answer, no charge.

If no provider is eligible or every provider fails, the response costs 0 credits and usually carries invalid with reason no_results.

Keeping autocomplete affordable

Autocomplete bills per request, and a user typing an address can generate many. The sessionToken field correlates a session's keystrokes for your own analysis but does not currently deduplicate charges. To keep costs predictable:

Debounce input (the hosted widget uses 250 ms by default) and require a minimum length (widget default: 3 characters).
Set country so providers without coverage are skipped.
Keep limit at the smallest useful value.
Let repeat queries hit the cache; they cost nothing.

Plans and quotas

Plan	Price / month	Credits / month	Active projects
Free	€0	500	1
Starter	€3	10,000	3
Growth	€9	50,000	Unlimited
Scale	€29	250,000	Unlimited

The monthly grant resets on the 1st of each calendar month (UTC). Usage is counted from the ledger of stored usage events, so it is exact; the displayed number can lag by up to 60 seconds but never overstates what you used.

Credit packs

One-time credit packs never expire and are consumed only after the monthly grant is used up: 50,000 for €12, 100,000 for €22, 500,000 for €100. Packs are priced above the per-credit rate of any subscription on purpose. Plans are the commitment; packs cover overflow without forcing an upgrade.

Plans and packs are attributed by the email address used at checkout, matched against your account email. Use the same address for both, or contact support to have a purchase reattributed.

When credits run out

Once monthly plan credits plus purchased extra credits are used up, authenticated /v1 endpoints return 429 before doing any work:

HTTP/1.1 429 Too Many Requests
Content-Type: application/json

{
  "message": "Monthly credits exhausted (500 plan credits on the free plan). Upgrade or buy credits at https://geoverdict.com/dashboard"
}

The widget endpoint returns {"message": "Monthly project credits exhausted"} with the same status. Neither response carries a Retry-After header: the fix is to upgrade the plan or buy a pack in the console, or wait for the monthly reset. Handle this distinctly from a transient rate limit; retrying immediately will not help.

Monitoring usage

GET /v1/usage reports the current month for the key's account without consuming a credit:

curl -s https://geoverdict.com/v1/usage \
  -H "Authorization: Bearer $GEOVERDICT_API_KEY"

It returns plan, quota, extraCredits, and creditsUsedThisMonth, plus a 14-day daily series, current-month totals by endpoint and verdict, totals per source tag, and the 50 most recent events. Add ?source=checkout to filter the summary, daily, and recent lists to one tag (the sources breakdown always stays account-wide). Tag your calls with source to see exactly which of your systems spends what. Because /v1/usage shares the API-key quota gate, it is unavailable after credits are exhausted; the console remains the place to inspect and resolve an exhausted balance.

Rate limits

Surface	Limit
Live `/v1/validate`, `/v1/autocomplete`, `/v1/usage`	No fixed request-rate limit. Your live credit balance is the cap.
Test `/v1` credentials	Best-effort 60 requests per minute per test key. Test keys bill from the same credit balance as live keys.
`/v1/widget/autocomplete`	Live tokens: 120 requests/minute per token and per origin. Test tokens: best-effort 60/minute per token, 120/minute per origin.
`/demo/validate`	Per visitor IP, rolling: 10 per 5 minutes, 20 per 24 hours, 50 per 7 days, 200 per 30 days.

The demo limiter's 429 lists every exhausted window and the exact wait, and sets a Retry-After header. API/widget rate-limit 429s do not set Retry-After; back off and retry within the next minute. A daily test-cap 429 clears at 00:00 UTC.

Getting started