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. The part that bit me: different endpoints are on completely different versions at the same time. Obligations is on v3.0, the self-employment cumulative summary is on v5.0, calculations are on v8.0, ITSA status is on v2.0. There is no single "current" version to pin. The fix was to make the version a required argument on the request wrapper so you can never forget it, and set it per call: // src/services/hmrcApi.ts const headers = { Authorization : `Bearer ${ accessToken } ` , Accept : `application/vnd.hmrc. ${ apiVersion } +json` , // e.g. "5.0" ... hmrcConfig . getFraudHeaders ( req ), }; One more trap: versions get withdrawn. Obligations used to answer on v2.0; that now returns a 404, not a 406, so it looks like a missing resource rather than a stale version. When an HMRC call 404s, check the version before you go hunt