Errors

Error format

Errors return a JSON body with a human-readable error. Some add a machine-readable code, and validation errors add fields:

{
  "error": "Please correct the highlighted fields.",
  "fields": {
    "work_email": "A valid email address is required.",
    "issue_date": "Use a date in YYYY-MM-DD form."
  }
}

{
  "error": "That record is not eligible for third-party verification. Only active records issued by an organisation can be checked.",
  "code": "RECORD_NOT_ELIGIBLE"
}

Branch on the HTTP status and code. The error text is written for people and may change. Responses do not include a request or correlation ID.

Status codes

Error codes

Retrying safely

• Wait for Retry-After on 429, and back off exponentially on 500 and 503.
• Retrying a credential issuance is safe when you send the same body with an explicit issue_date. See Idempotency.
• Do not blindly retry POST /api/v1/verifications: each accepted call creates a new request. If it returns 500 with a request_id, the request exists already.
• Never retry 400, 401, 403 or 404 unchanged.