Errors
The problem+json envelope, and what each status means.
This page is about HTTP failures. A check that runs and finds something is not an error — see statuses and outcomes for those.
The envelope
Errors use RFC 7807 problem details,
served as application/problem+json:
{
"type": "about:blank",
"title": "Validation failed",
"status": 400,
"detail": "reports[0].checksRequested must contain at least one check",
"instance": "/api/v1/reports",
"errorCode": "REQ_VALIDATION_FAILED",
"timestamp": "2026-09-09T08:14:22Z"
}Branch on errorCode. detail is written for a person reading a log, and its
wording can change.
Every response carries X-Request-Id. Quote it when reporting a problem — it is
what makes a single request findable.
Status codes
| Status | Meaning |
|---|---|
200 OK | Read or update succeeded. |
201 Created | Reports or a reference was created. |
202 Accepted | Accepted for asynchronous processing — a resend, a test event. |
204 No Content | Succeeded, with nothing to return. |
400 Bad Request | Validation or request-shape failure. |
401 Unauthorized | Missing, malformed, invalid, inactive, expired, environment-mismatched, or endpoint-restricted API key. Most often a malformed header. |
403 Forbidden | The key lacks the required scope. |
404 Not Found | Resource, route, or sandbox fixture does not exist. |
409 Conflict | The report's lifecycle state does not allow this. |
429 Too Many Requests | Rate limit exceeded. |
The ones that catch people out
401 on a key you know is valid. Check the header before the key: the word
Bearer and one space have to precede it on Authorization. The environment
is part of validation too, so the key prefix must match the host.
The header, spelled out.
403 where you expected 401. The key authenticated but lacks the scope.
409 on a report. Its lifecycle state does not allow what you asked —
typically consent or payment is still outstanding. Read
consent state, or the
paymentState on the report, rather than
retrying.
404 in sandbox only. SANDBOX_ROUTE_NOT_FOUND and
SANDBOX_FIXTURE_NOT_FOUND mean there is no fixture, not that your request was
wrong.