Skip to main content

Error codes & troubleshooting

Errors are returned with a standard HTTP status code and a JSON body describing the problem. This page lists the ones you are most likely to encounter.

The error body​

Error responses are not wrapped in the usual meta/data envelope — the body is a flat object:

{
  "message": "Too much data was requested. …",
  "error_code": 4,
  "request_id": "1234-abcd",
  "extra": {}
}
  • message — a human-readable description of what went wrong.
  • error_code — a stable integer identifying the error type (e.g. 1 bad JSON, 2 resource not found, 3 invalid input, 4 too much data, 18 too many requests, 19 request timeout). Match on this rather than on message wording, which may change.
  • request_id — include this when reporting a problem; it lets YouGov find the request in the logs.
  • extra — optional structured detail about the error.

Status codes​

StatusCauseWhat to do
400 Invalid inputA malformed request — e.g. an invalid period, a filter with the wrong value type, or an unknown metric.Fix the offending field. See the relevant concept page.
400 Too much dataThe request asks for more than the per-request ceiling.Reduce brands, period length, metrics, or the moving average. See Limits & quotas.
401 UnauthorizedNot authenticated on a protected endpoint, or an account disabled for abuse.Re-authenticate; contact YouGov if disabled.
403 ForbiddenAuthenticated, but the resource is outside your entitlements.Request access, or query data you are licensed for.
404 Not foundAn unknown UUID (analysis, ranking, event, tag…) — or a failed POST /v1/auth/login (wrong password or unknown email).Check the identifier; for login, check the credentials.
408 Request timeoutThe request took too long to process.Retry; reduce the request size if it persists.
413 Payload too largeAn uploaded file exceeds the maximum size.Reduce the upload size.
422 UnprocessableThe request body is not valid JSON.Fix the JSON syntax (note: this is distinct from 400, which means well-formed JSON with invalid content).
429 Too many requestsRate/volume limit hit within a time window.Back off and retry after a pause.
5xxA transient server problem.Retry with backoff; contact support if it persists.

Common cases explained​

"Too much data was requested"​

The request's days × metrics × brands cost exceeded the limit. Remember that index counts as six metrics and "all brands" entities expand to many brands. See Request size & limits.

Invalid period​

Check the period rules: end ≥ start, no relative-start + absolute-end, no future dates, and the offset-period constraints.

Invalid filter values​

Value-based filters expect the right value type (integers vs. strings) and a valid operator. See Filters and look values up in the filters catalogue.

Reporting a problem​

The API is a technical service, so debugging an integration is the developer's responsibility in the first instance. When a request fails, gather:

  1. The URL of the request.
  2. The HTTP method, and for POST the request body.
  3. The HTTP response status code.
  4. The HTTP response body — it explains what went wrong, and its request_id lets the API developers find the request in the logs.

If you still cannot resolve it, send those four items to your YouGov Client Services representative — the API developers use them to investigate.