Every failure the API returns, from every operation, has the same body, except that Retrieve a verification request takes no echo token, so its metadata carries timeStamp only. The individual messages live on each operation's own page; this page describes the envelope they arrive in. Two failures come from the gateway in front of the API instead and have a body of their own, see Errors from the gateway below.

Status codes

Status Meaning Returned by
400 The request was rejected: it could not be parsed, a value failed validation, or the operation is not allowed for this request (for example a reused echo token). Each operation's page lists its messages. All operations
401 The subscription key is missing or not valid. Returned by the gateway; see Errors from the gateway below. All operations
404 The verification or reservation named in the request was not found. Modify, Cancel, Retrieve
429 More than 12,000 calls in 60 seconds on one subscription key. Returned by the gateway, with a Retry-After header. See Errors from the gateway and Rate limiting below. All operations
500 An unexpected error. The body carries a short reference code rather than a description. All operations

A screening outcome is not an error. A guest who is rejected or flagged returns 200, see the operation pages.

The body

Content-Type: application/problem+json.

Level Field Name Always Present Format Value Set Description
1 metadata True object Carries timeStamp and echoToken.
2 timeStamp True date-time yyyy-MM-ddTHH:mm:ss.ff The server's timestamp.
2 echoToken False string The token sent on the request, echoed back, or Unknown. Present on every operation except Retrieve a verification request, which takes no echo token.
1 type True string Link to the RFC 7231 section describing this status code.
1 title True string Bad Request, Not Found, Internal Server Error Short name for the status code, for example 'Bad Request'.
1 status True integer 400, 404, 500 HTTP status code, repeated in the body.
1 detail True string What went wrong, in a form safe to log. When several validation rules fail, every message is included.
1 instance True string The method and path that produced the error, for example 'POST /verificationRequests'.

Two things to know about the body

detail carries every failure at once, as one string. When several rules fail, the messages are joined with a single space. There is no array and no field key. A response may contain many sentences run together, and parsing them apart means splitting on the message text itself.

echoToken is Unknown when the token could not be read. The token is read from the request body, so a body the parser rejects (not valid JSON, or a field holding the wrong kind of JSON value) or one without a metadata object, has no token to echo. Some unexpected errors (500) also return Unknown, so keep the token that was sent: support will need it. Any other failure echoes back the token that was sent, even when that token failed validation.

Examples

A validation failure, with two rules failing at once:

{
  "metadata": {
    "timeStamp": "2026-09-03T14:31:07.55",
    "echoToken": "6f2b1c4e-9d3a-4f18-b7c5-2e8a41d09b63"
  },
  "type": "<https://datatracker.ietf.org/doc/html/rfc7231#section-6.5.1>",
  "title": "Bad Request",
  "detail": "checkIn must not be in the past. extendedAmount must be included with Complete Protection.",
  "instance": "POST /verificationRequests",
  "status": 400
}

An echo token that has already been used:

{
  "metadata": {
    "timeStamp": "2026-09-03T14:31:09.02",
    "echoToken": "6f2b1c4e-9d3a-4f18-b7c5-2e8a41d09b63"
  },
  "type": "<https://datatracker.ietf.org/doc/html/rfc7231#section-6.5.1>",
  "title": "Bad Request",
  "detail": "echoToken (6f2b1c4e-9d3a-4f18-b7c5-2e8a41d09b63) already exists from a previous request",
  "instance": "POST /verificationRequests",
  "status": 400
}

An unexpected error:

{
  "metadata": {
    "timeStamp": "2026-09-03T14:31:07.55",
    "echoToken": "Unknown"
  },
  "type": "<https://datatracker.ietf.org/doc/html/rfc7231#section-6.6.1>",
  "title": "Internal Server Error",
  "detail": "Create Verification Error Code 01",
  "instance": "POST /verificationRequests",
  "status": 500
}

On a 500 the detail is a short reference code, not a description. Quoting it to support, together with the echo token that was sent, identifies the request.

Errors from the gateway

A 401 and a 429 are returned by the gateway before the request reaches the API. They carry the gateway's own body rather than the one above: Content-Type: application/json, with no metadata and no echo token.