Documentation menu
Rate limits and quota
Three refusals get conflated as rate limiting. Handle each one differently.
Looking up one address, parcel or property costs one credit. A page of search results costs one credit per 20 results, and the full detail of one record costs one credit. Anything your organization already paid for is free to fetch again for 24 hours, and a call that finds nothing, or reaches a jurisdiction Placestack does not cover, is free. Every response's meta.cost tells you what it spent, and free_reason says why when it spent nothing.
Which refusal you got
- 429rate_limited
- Too many requests too quickly. The response carries Retry-After. Wait that long and retry; the call itself was fine.
- 402quota_exhausted
- The organization has spent what it had. Credit is prepaid and the balance cannot go below zero, so add credit rather than retrying.
- 403entitlement_missing
- The plan does not include this, or you are already watching as many places as it allows. A retry or a top-up does not fix it; a bigger plan, or removing a watch, does.
{
"detail": {
"error": {
"code": "quota_exhausted",
"field": null,
"detail": "A spend of 5 credits would take the balance below zero.",
"message": "You are out of credits.",
"message_title": "Out of credits",
"request_id": "req_01h455vb4pex5vsknk084sn02q"
}
}
}Limits and headers
There are no RateLimit headers to read ahead of time, so treat a 429 as the signal and back off for the Retry-After it gives you rather than an interval you guessed. Your credit balance is in the console, under Billing.
Checking your balance
GET /entitlement is what the organization may do and what it has left: the feature map, and credit_balance. GET /usage is what it has spent and on what, over a window of up to 365 days, broken down by day, by endpoint and by key. It separates free_requests, the calls that cost nothing and were not errors, from the ones that cost something.
Price an expensive question before you ask it. Pass dry_run=true to /rule, /permission or /extract and you get the scope and the cost back, with nothing charged.
Retries and writes
Send an Idempotency-Key on every mutation, and a retried create returns the first result instead of making a second one. Updates require If-Match: a stale one comes back version_conflict rather than overwriting whoever got there first, so re-read and try again.