Errors, limits and freshness
Errors
Every error is an RFC 9457 problem
document with content type application/problem+json:
{
"type": "https://datatracker.ietf.org/doc/html/rfc9110#name-400-bad-request",
"title": "Area not available for pay",
"status": 400,
"detail": "Pay by detailed occupation is published for the UK, the nine English regions, Wales and Scotland: uk, wales, scotland, north-east, ... ONS does not publish it for England as a whole or for Northern Ireland."
}
title is stable enough to branch on; detail is written for a developer
reading it and may change.
| Status | When |
|---|---|
400 |
A parameter is invalid: an unknown measure, breakdown or area, or an area that has no data of that kind. detail lists the valid values. |
401 |
The X-API-Key header is missing, or the key is unknown or revoked. A key is revoked when you get a new one for the same email address. |
404 |
The SOC code does not exist, or there is no figure for that combination. The title says which - "No estimate" means ONS publishes nothing for it, usually because the sample is too small. |
429 |
Rate limit reached. See below. |
Rate limits
Limits are per key, per minute.
| Tier | Requests per minute |
|---|---|
| Free | 60 |
| Standard | 1,000 |
| Unlimited | 10,000 |
The open /v1/meta endpoints are limited to 60 per minute per IP address.
A 429 response includes a Retry-After header giving the seconds to wait.
Wait at least that long before retrying.
How fresh the data is
The underlying data changes slowly - pay yearly, employment quarterly - so responses are cached:
| Endpoints | Cached for up to |
|---|---|
/pay |
6 hours |
Search, occupation, /pay/series, /pay/regions, /employment, /skills, /meta/sources |
24 hours |
/meta/editions |
5 minutes |
/meta/ingest |
not cached |
So after a new release is published, responses can take up to a day to reflect
it. /meta/ingest and /meta/editions are always current if you need to know
exactly what is being served.
Caching your own copy of responses is fine and encouraged. A day is a sensible
default; to be sure you have the latest release, compare provenance.edition
with /v1/meta/sources.
When new data arrives
| Data | Typically released |
|---|---|
| Pay, provisional | October-November |
| Pay, revised | the following spring |
| Employment | quarterly |
| Occupations | irregularly |
| Skills | irregularly; checked monthly |
The service checks every source daily and publishes a new release only after it
passes validation. A release that fails is held back, and the previous one
keeps being served; /v1/meta/editions shows it as quarantined.