Credits, limits and errors

Credits

Requests spend credits from your account. API and MCP requests share the same balance and the same prices. The field catalog and support requests are free.

Request	Credits
A location lookup (address or coordinates) with its parcels	1 credit
Each lookup section: utilities, environment, logistics, data centers, power, grid, parcel boundaries	+1 credit
Each lookup section: terrain	+2 credits
Each address, point or parcel ID in an enrich batch (up to 25 per request)	1 credit
Each enrich item with owner fields (available on request, opt-in per organization)	2 credits
A record by ID: a parcel, power plant, data center, utility or other record	1 credit
A question answered by Ask, with cited sources	10 credits
Support requests and the field catalog	Free

The price depends only on the request, so you know it before you send it: a lookup costs 1 credit plus its sections, an enrich costs its item count times 1 credit (2 credits with owner fields), and every response reports credits.charged and credits.refunded. Each route's cost is listed in the API reference and in GET /v1/fields.

Requests spend your plan's monthly credits first, then any extra credits you've bought.
Monthly credits reset at the start of each calendar month (UTC). Unused monthly credits carry over once, into the next month.
You can buy extra credits on your account page at your plan's rate.
When credits run out, requests return 429. Nothing is charged automatically.

{
  "detail": "Monthly credits used up",
  "resets_at": "2026-12-01T00:00:00Z",
  "account_url": "https://app.korzy.co/account"
}

Refunds

Any request that returns an error status (400 or higher) is refunded in full.
Enrich items that fail (status: "error") and lookup sections that fail or are unavailable are refunded; the response's credits.refunded says how many.
An Ask stream that ends without a done event is refunded.

Owner fields

Owner name, mailing address and type are returned only by POST /v1/enrich when you ask for the owner group or one of its fields, at 2 credits per item. Lookup, records and Ask never return them. Organizations without owner data get 403 owner_data_unavailable, uncharged.

Rate limits

Each user has a per-minute request limit set by the plan. The limit counts every request, including free ones, and resets at the start of each minute (UTC).

Plan	Monthly credits	Requests per minute
Professional	3,000	300
Business	15,000	1,200

Each organization can also ask at most 6 Ask questions a minute and 200 a day (429 ask_rate_limited), and send at most 10 support requests an hour and 30 a day (429 support_rate_limited).

Over a limit, requests return 429 with a Retry-After header giving the seconds until you can retry. Wait at least that long. Higher limits are available on Enterprise plans.

Batch sizes

A lookup returns up to 20 parcels at the point; parcels.truncated is true when there are more.
An enrich takes up to 25 items and returns up to 20 records per item. Send larger lists as several requests.
These are lookup APIs, not bulk exports. For full-dataset licensing, contact us.

Errors

Errors return JSON with a detail message and, where applicable, a machine-readable code. These apply to every route; each route's own codes are listed in the API reference.

Status	Code	Meaning
`401`		Missing, malformed, revoked or expired credential.
`402`	`subscription_required`	Your account has no active subscription. Choose a plan on your account page.
`403`		Your credential lacks the required scope (`api:read` for `/v1`, `mcp:read` for MCP).
`404`	`use_v1`	Unknown route. Paths under `/api` are not part of the public API; use `/v1`.
`405`		The route doesn’t accept this HTTP method.
`413`		The JSON body is larger than 64 KB.
`422`	`invalid_json`	A POST body is not a JSON object. Not charged.
`429`		Rate limit or monthly credits reached. Wait for `Retry-After`; monthly exhaustion also includes `resets_at`.
`500`		Something went wrong on our side. Refunded; retry with backoff.
`503`		Temporarily unavailable. Refunded; retry after `Retry-After` with backoff.

Retries

Retry 429, 500 and 503 only after Retry-After where given, with exponential backoff and a bounded number of attempts.
Don't retry other 4xx errors without changing the request.
The first request after a quiet period can take longer.
Every response includes an x-trace-id header, and successful ones a request_id. Include them in support requests.