Errors

Check the HTTP status before parsing the body. A non-2xx response is not guaranteed to use the same JSON shape as a successful evaluation.

Status	Meaning	Client action
`200`	Evaluation completed or returned an explicit incomplete decision	Parse the body; branch on `should_block`.
`400`	Malformed `X-Timestamp` or `X-Request-ID`	Send a valid current ISO 8601 timestamp and a fresh UUID.
`401`	Missing, invalid, or revoked API key; unsupported signature version; stale timestamp; missing signature; or signature mismatch	Do not retry unchanged. Correct authentication or signing.
`422`	JSON body failed schema validation	Correct the field names, required values, types, or constraints.
`500`	Unexpected evaluation or database failure	Treat the outcome as unknown and follow the reconciliation procedure.
`503`	A required service or security configuration is unavailable	Treat the outcome as unknown and follow the reconciliation procedure.

Authentication examples

Missing or malformed API key:

{
  "detail": "Missing or malformed X-API-Key header"
}

Stale timestamp:

{
  "detail": "Request timestamp is outside the 5-minute window (potential replay attack)"
}

Signature mismatch:

{
  "detail": "X-Signature mismatch — request body may have been tampered"
}

Validation errors normally return a detail array containing a location and message:

{
  "detail": [
    {
      "type": "missing",
      "loc": ["body", "transaction", "source_account_id"],
      "msg": "Field required"
    }
  ]
}

Do not retry a 400, 401, or 422 response without changing the invalid request or credentials.

For 500, 503, timeouts, and connection failures: