specification: API Commons Rate Limits
specificationVersion: '0.1'
schema: https://raw.githubusercontent.com/api-evangelist/interface-research/main/schema/api-commons.yml#/$defs/RateLimits
provider: HMRC UK Tax Authority
providerId: hmrc
created: '2026-05-04'
# Provenance stamped 2026-08-11: this artifact was written by the API Evangelist
# bulk sweep dated 2026-05-04, not harvested from the provider. See roadmap#35.
method: generated
modified: '2026-05-05'
reconciled: true
tags:
  - Government
  - Making Tax Digital
  - Regulatory
  - Tax
  - UK
  - Rate Limiting
  - Throttling
description: HMRC's Developer Hub publishes a single, platform-wide per-application throttle of 3 requests
  per second, scoped to each registered application. Above that ceiling clients receive HTTP 429 with the
  HMRC error code MESSAGE_THROTTLED_OUT. Maintenance and capacity events surface as 503 (SERVER_ERROR or
  SCHEDULED_MAINTENANCE) and 504 (GATEWAY_TIMEOUT). Applications that legitimately need a higher rate must
  contact the HMRC Software Developer Support Team to discuss design and have the limit raised. There is no
  sandbox-specific number documented separately; sandbox is intended for functional testing rather than load
  testing.
sources:
  - https://developer.service.hmrc.gov.uk/api-documentation/docs/reference-guide
  - https://developer.service.hmrc.gov.uk/api-documentation/docs/terms-of-use
responseCodes:
  throttled: 429
  serviceUnavailable: 503
  gatewayTimeout: 504
limits:
  - tier: production
    name: Default per-application throttle (production)
    scope: application
    metric: requests_per_second
    limit: 3
    timeFrame: second
    applies:
      - HMRC VAT (Making Tax Digital) API
      - HMRC Self Assessment API
      - HMRC PAYE (Pay As You Earn) API
      - HMRC Customs Declarations API
      - HMRC Corporation Tax API
    notes: Steady-state ceiling. Returns HTTP 429 with code MESSAGE_THROTTLED_OUT when exceeded. HMRC
      explicitly favors real-time interactions over batching.
  - tier: production
    name: Raised limit (per agreement)
    scope: application
    metric: requests_per_second
    limit: 'negotiated; contact HMRC Software Developer Support Team'
    applies:
      - HMRC VAT (Making Tax Digital) API
      - HMRC Self Assessment API
      - HMRC PAYE (Pay As You Earn) API
      - HMRC Customs Declarations API
      - HMRC Corporation Tax API
    notes: Applications that consistently hit the 3 RPS ceiling can request an uplift after a design review
      with HMRC.
  - tier: sandbox
    name: Sandbox throttle
    scope: application
    metric: requests_per_second
    limit: 'sandbox not load-tested; same per-application throttle policy applies'
    applies:
      - HMRC VAT (Making Tax Digital) API
      - HMRC Self Assessment API
      - HMRC PAYE (Pay As You Earn) API
      - HMRC Customs Declarations API
      - HMRC Corporation Tax API
    notes: Sandbox is for functional testing only. HMRC does not publish a separate numeric throttle.
policies:
  - name: Backoff Strategy
    description: HMRC instructs clients to stop making additional API requests for a short period after
      receiving 429 / MESSAGE_THROTTLED_OUT, then retry. Implement exponential backoff with jitter.
  - name: Limit Uplift via Support
    description: Rate limits are raised on a per-application basis only after HMRC's Software Developer
      Support Team reviews the application's design and the business case for higher throughput.
  - name: Real-Time Bias
    description: HMRC explicitly designs the rate limit to discourage batching; vendors are expected to
      submit traffic in real-time as users perform actions.
  - name: Maintenance Windows
    description: Scheduled-maintenance traffic returns HTTP 503 with SCHEDULED_MAINTENANCE; clients should
      retry after the published downtime window.
  - name: Fraud Prevention Headers
    description: HMRC requires fraud-prevention headers (Gov-Client-*) on every request. Missing or invalid
      headers can result in 403 errors independent of rate limiting.
maintainers:
  - FN: Kin Lane
    email: kin@apievangelist.com