5 things that surprised me building on HMRC's Making Tax Digital API

I spent the last while building the HMRC integration for TapTax, a Making Tax Digital (MTD) app for UK sole traders. MTD is the UK government's programme that pushes tax filing out of paper and spreadsheets and into software talking directly to HMRC's APIs.

I have integrated with a fair few third-party APIs. Stripe, Plaid-style banking, the usual. HMRC is its own animal. Some of it is genuinely well designed, some of it caught me completely off guard, and a couple of things cost me a full day each before the penny dropped.

So here are the five things that surprised me most. Each one is the surprise, then the fix, with a short snippet from our actual TypeScript backend. Not tax advice, just engineering notes from someone who has now stepped on the rakes so you do not have to.

1. The API version lives in the Accept header, and getting it wrong is a 406

Most APIs version in the URL: /v2/thing. HMRC versions through content negotiation. You ask for a version in the Accept header, like application/vnd.hmrc.5.0+json, and if you ask for a version that endpoint does not serve, you get a 406 Not Acceptable. No helpful "did you mean v3" message. Just 406.