Responses and errors

KYC and Financial answers have different shapes, and errors have one shape for both.

KYC answers: the envelope#

Every /v1 endpoint answers in the same envelope. The result is in data.

JSON

{
  "ok": true,
  "request_id": "req_cd1d47ea5bf34b7aae6c",
  "latency_ms": 2362,
  "data": { "match": true, "similarity": 0.9984, "threshold": 0.75 },
  "warnings": [],
  "error": null
}

okboolean: true when the check ran.
request_idstring: Identifies this call. Quote it when you contact us.
latency_msinteger: How long the call took on our side, in milliseconds.
dataobject: The result. Each endpoint's fields are in the API reference.
warningsstring[]: Things worth knowing that didn't stop the check, such as a low-quality image.
errorobject | null: null on success.

The libraries return data directly, and keep request_id and latency_ms on the result's response info.

Financial answers: the object#

/v2 endpoints answer with the object itself, without an envelope. Most carry an object field naming what they are, such as cheque_read or card_check.

Errors#

An error answers with a non-2xx status and this body:

JSON

{
  "ok": false,
  "request_id": "req_8f1a2c3d4e5f6a7b8c9d",
  "error": {
    "code": "invalid_input",
    "message": "image1 is not a valid image.",
    "param": "image1"
  },
  "warnings": [],
  "data": null
}

error.codestringrequired: A stable, machine-readable code such as invalid_input, missing_key or insufficient_credits. Branch on this, not on the message.
error.messagestringrequired: A sentence for a developer.
error.paramstring: The field the error is about, when there is one.

Status codes#

Status	Meaning	Library error
`400` `413` `415` `422`	The request is wrong: a missing field, an image that can't be read, a file that's too large or of the wrong type.	`InvalidRequest`
`401`	No key, or a key that's wrong or revoked.	`Authentication`
`402`	Not enough credits, or the key's spending cap is reached. Nothing was charged.	`InsufficientCredits`
`403`	The key isn't allowed this call: the API, the IP address or the key's expiry.	`Permission`
`404`	No such endpoint or record.	`NotFound`
`429`	Too many requests. Wait for `Retry-After` seconds.	`RateLimit`
`5xx`	Something failed on our side. Nothing was charged.	`APIServer`

Every library error carries the status, code, message, param and request_id. The exact class names per language are on each SDK page.