Vepler logo
v5.20.0 Breaking change

A deferred title deed purchase answers 202, and says whether you were charged

A purchase that HM Land Registry delivers out of band answers 202, and money_state on each money-bearing response says whether credits were taken.

Changed

  • POST /v1/title-deeds/{titleNumber}/purchase answers 202 with a TitleDeedPurchasePending body when HM Land Registry accepts the purchase and delivers the title out of band. Treat it as a success: the credits are taken and the purchase stands. money_state reads charged, expected_response_at carries the estimate where HM Land Registry supplied one, and GET /v1/title-deeds/{titleNumber}/purchase-status settles into 200 once the title arrives. A client that branches on 200 alone, or that treats anything other than 200 as a failure, needs a branch for this, and a platform reselling a title must not refund its own customer against a 202.
  • money_state states whether an attempt took credits. It is one of charged, not_charged or unknown, and it is stamped where the refund decision is made rather than worked out afterwards. On POST /v1/title-deeds/{titleNumber}/purchase it is on the 202, the 402, and the 404, 500, 502 and 503. A 200 does not repeat what the status already says, and the 400 and 401, refused before a purchase begins, carry the standard error body. GET /v1/title-deeds/{titleNumber}/purchase-status carries it on every response it owns, and on POST /v1/title-deeds/{titleNumber}/purchase-async it is on the 402. Read it to decide whether to refund downstream, retry cleanly, or hold for reconciliation: charged means the purchase is live, not_charged means nothing is held and a retry is safe, and unknown means hold.
  • The 404, 500, 502 and 503 on the synchronous purchase are typed as TitleDeedPurchaseError, which declares error.type, error.code, error.message and money_state. Regenerate your client from the current specification if it reads error.param, error.doc_url or error.suggestions on those four responses, or branches on an error.type of rate_limit_error there. The API populated none of them on those responses, so no value on the wire changes; the generated types stop declaring them. Rate limiting is still reported as 429.
  • money_state is required on InsufficientCreditsError, so a 402 always states the position on money. It reads not_charged: a declined purchase holds nothing, and error.required_credits on the same body tells you the credits the purchase costs, against error.current_balance for what the account held.

Affected endpoints