Errors
The problem+json envelope, and what each status means.
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.
Gateway responses carry 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 launch, a resend, a test event. |
204 No Content | Delete succeeded. |
400 Bad Request | Validation or request-shape failure. |
401 Unauthorized | Missing, invalid, inactive, expired, environment-mismatched, or endpoint-restricted API key. |
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 — for example launching one whose consent or payment is outstanding. |
429 Too Many Requests | Rate limit exceeded. |
The ones that catch people out
401 on a key you know is valid. The environment is part of validation —
check the key prefix matches the host.
403 where you expected 401. The key authenticated but lacks the scope.
409 on launch. The report is waiting on consent or payment. 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. Nothing was forwarded to a paid provider.