Guide
Errors
Error codes, what they mean and what to do.
Errors return JSON with a machine-readable code and a plain message: { "error": { "code": "invalid_payload", "message": "nin: must be 11 digits" } }. Every response carries a Request-Id header; quote it to support.
Status codes
| Status | What to do |
|---|---|
| 400 invalid_payload | A field is missing or malformed. The message names it. |
| 401 | Missing or wrong API key. |
| 402 insufficient_funds / budget_exceeded | Top up the wallet, or raise the monthly cap in the console. |
| 403 | The product isn't enabled for your business, or live checks aren't open to it yet. |
| 423 identity_locked | The owner locked this NIN or BVN in the Verath app. Ask them to unlock it, or allow your business once. Never billed. |
| 409 | This Idempotency-Key was used with a different body, or the first request is still running. |
| 424 upstream_unavailable | No source answered. The check is pending and retried automatically for up to 72 hours. Never billed. |
| 429 | Too many requests. Wait for the Retry-After header. |
What’s billed
A completed check is billed whether or not the number was found. Errors, pending checks, checks that fail after 72 hours, locked IDs and idempotent replays are never billed. The cost field on every check says what was charged.