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

StatusMeaning
200 OKRead or update succeeded.
201 CreatedReports or a reference was created.
202 AcceptedAccepted for asynchronous processing — a resend, a test event.
204 No ContentSucceeded, with nothing to return.
400 Bad RequestValidation or request-shape failure.
401 UnauthorizedMissing, malformed, invalid, inactive, expired, environment-mismatched, or endpoint-restricted API key. Most often a malformed header.
403 ForbiddenThe key lacks the required scope.
404 Not FoundResource, route, or sandbox fixture does not exist.
409 ConflictThe report's lifecycle state does not allow this.
429 Too Many RequestsRate 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.

On this page