Errors

Every call returns errors in the same shape: RFC 9457 problem details. Each error has a type URL that opens a page here explaining it.

The shape of an error

{
  "type": "https://developers.checkmystreet.co.uk/errors/outside-coverage",
  "title": "Outside coverage",
  "status": 422,
  "detail": "We value properties in England and Wales. EH1 1 is in Scotland.",
  "code": "unknown_sector"
}

Field	What it tells you
`type`	A URL that identifies the error. Branch on this in your code.
`title`	A short, fixed summary of the type.
`status`	The HTTP status, repeated in the body.
`detail`	What went wrong with this request, in words. Log it rather than parse it.
`code`	A more specific reason within the type.

Catalogue

Status	Type	When	What to do
`400`	`invalid-request`	Malformed JSON, an unknown field, a bad value	Fix the request. Retrying it unchanged fails again.
`401`	Token	Missing, invalid or expired token	Get a new token, then retry.
`403`	`insufficient-credits`	The balance does not cover the call	Top up by card, then retry.
`403`	`account-blocked`	The account is suspended	Contact us.
`404`	`not-found`	An unknown id, or nothing held for a postcode	Check the id you stored.
`409`	`request-in-progress`	Same `Idempotency-Key` while the first call runs	Wait, then retry with the same key.
`422`	`outside-coverage`	The postcode is outside England and Wales	Do not retry.
`422`	`floor-area-required`	The bedrooms could not be turned into a floor area	Send `floorAreaSqm`.
`422`	`idempotency-key-reused`	The same key arrived with a different request	Use a new key for a new request.
`429`	`rate-limited`	Too many requests in a short time, or the daily limit (`"code": "daily_limit"`)	Wait the seconds in `Retry-After`. For the daily limit, stop until midnight UTC.
`503`	`data-unavailable`	Something we rely on was unavailable. Never charged.	Retry shortly, with the same key.
`504`	`timeout`	The call ran past 30 seconds	Retry with the same key.

Token errors

401 means the token is missing, invalid or expired. It is checked before anything else, so its body is an OAuth error such as {"error": "invalid_token"} rather than a problem document. Get a new token, then retry the call once.

Handling errors in code

Branch on type, and treat anything you do not recognise as a failure you log:

if (!res.ok) {
  const problem = await res.json();
  switch (problem.type) {
    case "https://developers.checkmystreet.co.uk/errors/outside-coverage":
      return showMessage("We can only value homes in England and Wales.");
    case "https://developers.checkmystreet.co.uk/errors/timeout":
    case "https://developers.checkmystreet.co.uk/errors/data-unavailable":
      return retryWithSameKey();
    default:
      throw new Error(`${problem.status} ${problem.title}: ${problem.detail}`);
  }
}

In test mode, the magic postcodes return most of these errors on demand.