BOIVA Developer Hub

Integrate identity verification with confidence

Quickstarts on boiva.id, exact endpoint contracts in the canonical ReadMe API reference.

errors[]

Handle documented BOIVA errors explicitly

An unsuccessful response includes an event identifier and an array of errors. Each error contains a numeric error_code and a human-readable message.

Documented response shape

Preserve the event identifier in secure operational logs so support teams can trace the request. Never log credentials or raw identity payloads.

{
  "event_id": "{event-id}",
  "errors": [
    {
      "error_code": 100299,
      "message": "{human-readable message}"
    }
  ]
}

How to read a six-digit error code

The documented code groups service, error type, and specific error into three two-digit segments.

10····

API service

Examples documented by BOIVA include 10 for token generation, 11 for identity and selfie verification, and 12 for BOIVA ID verification.

··01··

Error type

01 denotes a user-generated error; 02 denotes a server-generated error.

····99

Specific error

The final pair identifies conditions such as missing headers, expired tokens, invalid keys, or unavailable sandbox quota.

Documented common suffixes

Use the complete code returned by the API. These suffixes explain the final two digits only.

99General error

98Missing header

97Invalid header

96Inactive client

95Missing query parameter

94Out of scope

93Expired token

92Invalid token

91Invalid API key

90No sandbox quota

89Inactive API

Request or credential issue

Correct the header, parameter, scope, client state, token, or key before sending another request. Do not blindly retry invalid input.

502 or 503 response

Treat the outcome as unavailable, keep the request traceable, and follow the retry behavior agreed in your production contract.

Verification mismatch

A returned verification signal is not automatically a transport error. Route mismatches and normalization states through your documented decision policy.

Contract boundary: do not invent string error names, HTTP mappings, or retry schedules that are absent from your assigned contract. Use the exact current response and canonical BOIVA reference.

Open the canonical error-code reference