Documentation Index
Fetch the complete documentation index at: https://docs.vouchmark.com/llms.txt
Use this file to discover all available pages before exploring further.
Every error response has the same shape:
{
"success": false,
"statusCode": 400,
"message": "Company RC number is required for TIN verification",
"error": "RC_REQUIRED",
"timestamp": "2026-05-12T09:14:00Z",
"path": "/v1/check-firstin"
}
error is the stable, machine-readable code. message is for humans and may change over time.
Status codes
| Status | Meaning | Retry? |
|---|
400 | Invalid input or precondition failed | No — fix the request. |
401 | Authentication failed or token expired | Refresh and retry. |
403 | Authenticated but not authorised | No. |
404 | Resource not found, or not owned by you | No. |
409 | Conflict (duplicate, race) | Sometimes — see the error code. |
413 | Payload too large | No — shrink. |
415 | Unsupported file type | No — re-encode. |
422 | Validation failed (Zod) | No — fix the body. |
429 | Rate limit hit | Yes, after Retry-After. |
500 | Server error | Yes, with exponential backoff. |
502/503/504 | Upstream issue | Yes, with backoff. |
Common error codes
Auth
| Code | Status | When |
|---|
NO_TOKEN | 401 | Authorization header missing. |
TOKEN_EXPIRED | 401 | Access token expired. Refresh. |
TOKEN_REVOKED | 401 | Token blacklisted (logout, password change). |
EMAIL_NOT_VERIFIED | 403 | Account exists but email confirmation pending. |
INVALID_CREDENTIALS | 401 | Wrong email or password. |
REFRESH_TOKEN_REUSED | 401 | The refresh token has already been used. Force re-auth. |
Validation
| Code | Status | When |
|---|
VALIDATION_ERROR | 422 | Body or query failed Zod schema. The response includes a details array of per-field problems. |
INVALID_FILE_TYPE | 400 | Uploaded file had the wrong MIME type. |
FILE_SIZE_LIMIT_EXCEEDED | 413 | Upload exceeded the per-endpoint size cap. |
FILE_COUNT_LIMIT_EXCEEDED | 400 | Too many files in a multi-upload request. |
Companies
| Code | Status | When |
|---|
COMPANY_NOT_FOUND | 404 | The company doesn’t exist or you don’t own it. |
RC_REQUIRED | 400 | Operation needs an RC number; none on file. |
ALREADY_IN_PROGRESS | 400 | A duplicate verification kickoff was attempted. |
RC_NOT_FOUND | 400 | CAC returned no record for this RC. |
Verifications
| Code | Status | When |
|---|
JTB_NO_TIN | 404 | JTB resolver returned no TIN. |
NAME_MISMATCH | 422 | Resolved name doesn’t match CAC. |
OCR_LOW_CONFIDENCE | 422 | Document text couldn’t be parsed reliably. |
BILL_STALE | 422 | Utility bill is older than 90 days. |
PROVIDER_NOT_ACCEPTED | 422 | Utility provider not on the supported list. |
ADDRESS_NO_MATCH | 422 | Bill address doesn’t match company address. |
ACCOUNT_NAME_NO_MATCH | 422 | Bank account name doesn’t match CAC. |
Trust Badge
| Code | Status | When |
|---|
BADGE_NOT_ELIGIBLE | 200 | Company isn’t eligible (score, sanction, missing CAC). Response has badge: null. |
INVALID_SIGNATURE | 200 | /trust-badge/verify — token signature doesn’t match. |
EXPIRED | 200 | /trust-badge/verify — token past expiresAt. |
REVOKED | 200 | /trust-badge/verify — badge revoked in DB. |
