API Custom Headers
As part of responses from the API, we include custom headers to provide extra information. Details of these headers are below. We recommend that you check for these headers and their values when you process responses from the API.
Rate limiting headers
To allow fair usage of the API across all users of the API, we have applied rate limiting to requests made to the API. For more information on how rate limiting works with the API click here.
So you can keep track of your current usage of the API and how this compares with your current limits, we return several custom headers with all responses from the API.
Header: 'RateLimit-Limit'
Format: The maximum number of requests allowed in the current window, eg: '30000'.
Header: 'RateLimit-Policy'
Format: The quota policy, where q is the value for the total quota, and w is the time window in seconds, eg: '"default";q=30000;w=600'.
Header: 'RateLimit-Remaining'
Format: The remaining requests in the current window, eg: '22500'.
Header: 'RateLimit-Reset'
Format: Seconds remaining until the current window resets, eg: '15'.
Trial licences
For users whose access is via a trial licence, we include a custom header to indicate the timestamp that your trial licence ends on. After this timestamp, your access to the API will end, unless you upgrade to a full licence. If your access is via a full licence, then this header will not be included in responses from the API.
Header: 'API-Trial-Licence-End-Date'
Format: This returns the timestamp that the trial licence is due to end on, eg: '2026-08-27T18:10:58Z'
Maintenance headers
Occasionally, the API will be unavailable due to scheduled maintenance. We do try to keep the frequency and duration of these occasions to a minimum. However to keep the API up to date with any changes in functionality or bug fixes, we occasionally need to take the API down for maintenance.
We therefore have included two custom headers which provide details of the next upcoming maintenance period of the API.
If there is no planned maintenance period coming up, then these custom headers will not be returned with any API responses.
Header: 'API-Maintenance-Date'
Format: This returns the timestamp that maintenance is expected to start, eg: '2026-09-01T09:00:00Z'.
Header: 'API-Maintenance-Duration'
Format: This returns the estimated duration of the maintenance window, eg: '1 hour' or '30 minutes'. Please note, this is only an estimate, the actual duration of the update may be longer or shorter. Once the update has been completed, then both headers will no longer be returned in responses.
Decommission and replacement of endpoints
From time to time we will need to either decommission an existing endpoint, or replace an existing endpoint with a new version of it. In advance of this happening, we will add headers to the endpoint being decommissioned or replaced as soon as we can. These will be in the following format:
Header: 'Deprecation'
Format: This will be the unix epoch value that the endpoint has been deprecated from preceded with an @ symbol, eg: '@1778544000' - this value corresponds to: 12 May 2026, 00:00:00 UTC.
Header: 'Sunset'
Format: When known, this header will be returned, which will state the date that the endpoint will be shut down on, using the standard HTTP date format, eg: 'Thu, 12 Nov 2026 00:00:00 GMT'
Header: 'Link'
Format: This will point users to migration guides where rel="deprecation" or replacement endpoints where rel="alternative", where this is relevant, eg: 'Link: <https://example.com>; rel="alternate", <https://example.com>; rel="deprecation"'
Note: We will aim to provide you with as much time to migrate away from endpoints which are being decommissioned or replaced, therefore we advise you to check for these headers on all endpoints.