Vepler API Documentation

Two limits apply to each account, across all of its API keys:

Limit	Default	Applies to
Suggest requests	600 a minute	`GET /v1/search/suggest`
Daily spend	50,000 credits a day, reset at midnight UTC	Every endpoint except suggest, `GET /v1/property/attributes`, the heritage and conservation `types` lists, flood risk, title deed reads and some health checks

The suggest limit allows a burst of up to 600 requests, then refills at 10 a second. Daily spend counts the credits charged each UTC day, search sessions included. Endpoints that cost nothing but are not exempt, such as postcode validation, still return 402 at a zero balance and 429 once the daily limit is reached. Your account can have different figures; the message in a 429 response states the one applied to it. To change them, email hello@vepler.com.

429 responses

Once you reach either limit, requests return 429 with a Retry-After header giving the seconds to wait:

{
  "error": {
    "type": "rate_limit_error",
    "message": "Rate limit exceeded: this account is limited to 600 suggest requests per minute.",
    "code": "rate_limit_exceeded"
  }
}

A 429 from GET /v1/search/suggest is the request limit, and Retry-After is short. A 429 from any other endpoint is the daily spend limit, and Retry-After runs to midnight UTC.

402 responses

When your balance has nothing left to spend, the endpoints covered by the daily spend limit return 402 until you top up in the dashboard:

{
  "error": {
    "type": "invalid_request_error",
    "message": "Insufficient credits. Please top up your balance or subscribe to a plan.",
    "code": "insufficient_credits"
  }
}

A 402 has no Retry-After: retrying does not help until your balance changes.

Retries

Only 2xx responses are charged, so a request that fails with a 429, 402 or 5xx costs nothing. Title deed purchases are the exception: see Errors. A request that timed out on your side may still have completed, and been charged, on the server; retrying it is charged again. The SDK does not retry by default; Retries shows how to turn it on. Keep the give-up time short, because a daily spend 429 does not clear until midnight UTC, and do not retry timeouts or dropped connections, since those requests may already have been charged. Without the SDK, wait at least the Retry-After interval before retrying.

Seeing what you spent

A charged response usually carries these headers:

Header	Value
`X-Credits-Charged`	Credits this request cost
`X-Credits-Balance`	Your balance after it
`X-Already-Charged`	`true` when nothing was charged because this request’s charge had already been recorded, otherwise `false`

They are left out when the charge takes longer to settle than the response; the charge still completes. Search session charges never appear in headers. The Requests page in the dashboard lists each request with what it cost, settled search sessions included, and the pricing page lists every rate. The pricing page also shows what one credit costs.

Spending less

Request only the property attributes you need. Each attribute’s tier is charged for every record returned; see Property attributes.
A repeat lookup of the same address or property is charged again unless your account has distinct-record billing; see Address billing.

Guides

Usage and limits

429 responses

402 responses

Retries

Seeing what you spent

Spending less

​429 responses

​402 responses

​Retries

​Seeing what you spent

​Spending less

429 responses

402 responses

Retries

Seeing what you spent

Spending less