Vepler API Documentation

A failed request returns a 4xx or 5xx status. Most error bodies look like this:

{
  "error": {
    "type": "invalid_request_error",
    "code": "uprn_not_found",
    "message": "UPRN not found: 999999999999",
    "param": "uprn"
  }
}

Field	Meaning
`type`	`invalid_request_error`, `authentication_error`, `rate_limit_error` or `api_error`.
`code`	Identifies the failure, for example `postcode_not_found` or `rate_limit_exceeded`. Branch on `code`, not on `message`. Some errors have none.
`message`	What went wrong, in words.
`param`	The parameter at fault, when the API can tell.
`suggestions`	Values to try instead. Only some not-found errors include it, such as an unknown postcode.

Other error bodies

Some failures use a different body, so do not assume error is always an object.

Status	When	Body
401	The API key is missing, wrong, expired or revoked, or the account has been deactivated	`{ "error": "API key required" }`
403	The key cannot use this endpoint	`{ "error": "Forbidden", "message": "..." }`
400	A parameter fails the endpoint’s schema, such as a `limit` above its maximum. Search suggest is the exception and uses the standard body.	`{ "success": false, "error": { "name": "ZodError", "message": "..." } }`, where `message` is a JSON-encoded array of the failing fields
400, 404, 500, 504	Some errors on `/v1/area-reference/...`	`{ "success": false, "error": "...", "details": "...", "code": "..." }`; `details` and `code` are not always present
404	The path matches no endpoint	Plain text: `404 Not Found`
500	An unexpected failure on the server	Plain text: `Internal Server Error`

An unknown path returns either 404 (plain text) or 403 with the message This endpoint is not available, depending on the path.

Status codes

Status	Meaning	Retry
400	The request is invalid.	No. Fix the request.
401	The API key is missing, wrong, expired or revoked, or the account has been deactivated. Send the key in the `x-api-key` header.	No
402	The account has no credit for a billable endpoint (`insufficient_credits`), or too little for a title deed purchase.	Once the account has enough credit
403	The account does not include this product, or a property query filters on an attribute that needs an extended permission.	No
404	Nothing matches the identifier you sent.	No
422	Valuation endpoints only: the request is valid but the property cannot be valued.	No
429	A rate limit or the account’s daily credit cap was reached.	After `Retry-After`
500	The server could not complete the request.	Yes, with backoff
502	Title deeds only: HM Land Registry could not be reached or rejected the purchase.	Yes, but read `money_state` first on a purchase
503	A dataset or service is briefly unavailable.	Yes, with backoff

Rate limits and credit

A 429 has the code rate_limit_exceeded and a Retry-After header giving the seconds to wait. Two limits produce it:

Search suggest allows each account a set number of requests per minute.
Billable endpoints share a daily credit cap per account, which resets at midnight UTC. Retry-After then counts down to midnight, so stop rather than retry.

The message states your account’s limit. A 402 has no Retry-After: the same request succeeds once the account has enough credit. See Usage and limits.

What a failed request costs

Requests that end in a 4xx or 5xx status are not charged. The exception is a title deed purchase: its error body carries money_state, which is charged, not_charged or unknown. Read it before you retry or refund. unknown means the outcome could not be established: call GET /v1/title-deeds/{titleNumber}/purchase-status, which reports what the account was charged, before retrying. A 202 means the purchase succeeded and is still being delivered; do not treat it as a failure.

With the SDK

SDK methods throw on any 4xx or 5xx response.

import { SDK } from "@vepler/sdk";
import { SDKBaseError } from "@vepler/sdk/sdk/models/errors";

const sdk = new SDK({ apiKeyAuth: process.env.VEPLER_API_KEY });

try {
  const address = await sdk.address.lookupUprn({ uprn: "100023336956" });
  console.log(address.formatted);
} catch (err) {
  if (!(err instanceof SDKBaseError)) throw err;
  console.error(err.statusCode, err.headers.get("retry-after"), err.body);
}

Every HTTP error is an SDKBaseError, with the raw response text in body. The subclass depends on whether the body matched the documented shape, so branch on statusCode rather than on the class. The SDK’s other error classes and its built-in retries are on TypeScript SDK.

Over HTTP

Read the body as text first, because some errors are plain text. This helper returns a code and message from any of the shapes above:

interface ApiError {
  status: number;
  code?: string;
  message: string;
}

async function readError(res: Response): Promise<ApiError> {
  const text = await res.text();
  try {
    const body = JSON.parse(text) as { error?: unknown; message?: unknown; details?: unknown; code?: unknown };
    if (typeof body.error === "object" && body.error !== null) {
      const { code, message } = body.error as { code?: string; message?: string };
      return { status: res.status, code, message: message ?? text };
    }
    const parts = [body.error, body.message, body.details].filter((part) => typeof part === "string");
    return {
      status: res.status,
      code: typeof body.code === "string" ? body.code : undefined,
      message: parts.join(": ") || text,
    };
  } catch {
    return { status: res.status, message: text };
  }
}

To retry a 429, 500, 502 or 503, wait for Retry-After when the response has one, back off exponentially when it does not, and cap the attempts. Give up when Retry-After runs to midnight UTC, and do not retry other 4xx statuses.

Getting Started

Concepts

Errors

Other error bodies

Status codes

Rate limits and credit

What a failed request costs

With the SDK

Over HTTP

​Other error bodies

​Status codes

​Rate limits and credit

​What a failed request costs

​With the SDK

​Over HTTP

Other error bodies

Status codes

Rate limits and credit

What a failed request costs

With the SDK

Over HTTP