Credits, limits and errors

Credits

Data requests spend credits from your account. API and MCP requests share the same balance. Discovery routes such as catalogs and summaries are free, so you can see what exists before you spend.

Request	Credits
Catalogs, summaries and status checks	Free
A record or lookup: a parcel, plant, utility or address search	1 credit
Pages of results, such as point lookups with several parcels or energy history tables	1 per 10 records
Ownership on a parcel or property-record lookup (include_owner=true)	+1 credit per record; pages +1 per 10 records

Page costs are based on the limit you request, or the route's default when you omit it, rounded up to the next 10 records. Each route's cost is listed in the API reference. An MCP tool can make several data requests.

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"
}

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

Over the 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.

Pagination

Paged routes return one page at a time. Control pages with limit and offset; each route documents its maximum limit, and offset stops at 1,000 (a deeper offset is a 422 offset_too_deep, not charged).

Responses include paging fields such as next_offset and truncated. A null next_offset means there are no more pages.
Many routes return a run_id naming the data snapshot. Pass it unchanged, with the same filters, on every later page.
If the data is updated while you page, the next request returns 409. Start again from the first page.
These are lookup APIs with offset caps, not bulk exports. For full-dataset licensing, contact us.

GET /api/energy/plants/3?limit=100
→ { "records": [...], "run_id": "…", "next_offset": 100, ... }

GET /api/energy/plants/3?limit=100&offset=100&run_id=…

Errors

Errors return JSON with a detail message, and a machine-readable code where one applies.

Status	Meaning
`400`	The request is malformed.
`401`	Missing, malformed, revoked or expired credential.
`402`	Your account has no active subscription (`code: subscription_required`). Choose a plan on your account page.
`403`	Your key or plan doesn’t include this route’s scope.
`404`	Unknown route or record ID.
`405`	The route doesn’t accept this HTTP method.
`409`	The data snapshot changed between pages. Restart from the first page.
`422`	A parameter is missing or out of range. The body says which.
`429`	Rate limit or monthly credits reached. Wait for `Retry-After`; monthly exhaustion also includes `resets_at`.
`503`	Temporarily unavailable. Retry after `Retry-After` with backoff.

Retries

Retry 429 and 503 only after Retry-After, with exponential backoff and a bounded number of attempts.
Don't retry 4xx errors other than 409 and 429 without changing the request.
The first request after a quiet period can take longer.
Every response includes an x-trace-id header. Include it when you contact support.