15. Error Reference¶
The single catalog of error codes a developer encounters. All platform error responses follow the envelope {error: {code, message, details?}}.
15.1 Platform HTTP Errors¶
Application-level error codes returned by the platform, with the originating endpoint surface and the section that specifies the behavior.
error.code |
HTTP | When | Spec |
|---|---|---|---|
tenant_suspended |
403 | Tenant is suspended; all API calls for the tenant are rejected |
§4.3, §4.8 |
consent_required |
403 | consent_required: true and the user has not granted consent (enrollment / device transaction) |
§11.1 |
palm_type_restricted |
403 | Submitted palm type is not allowed by the user's restriction (mapped from vendor code 30008) |
§8.11 |
| (duplicate enrollment) | 409 | Pre-enrollment duplicate detected with palm_duplicate_action: reject (audit palm_duplicate_detected) |
§8.10 |
pairing_code_invalid |
401 | /v1/devices/pair — code wrong, expired, or already consumed |
§9.2.1 |
pairing_rate_limited |
429 | /v1/devices/pair — source IP exceeded the pairing-code attempt rate limit |
§9.2.1 |
csr_invalid_algorithm |
400 | /v1/devices/pair, /v1/devices/renew — CSR public key is not ECDSA P-256 |
§9.2.1 |
csr_invalid_extensions |
400 | /v1/devices/pair, /v1/devices/renew — CSR contains privileged or non-permitted extensions (e.g. BasicConstraints CA:true) |
§9.2.1 |
csr_signature_invalid |
400 | /v1/devices/pair, /v1/devices/renew — CSR self-signature failed verification (proof-of-possession) |
§9.2.1 |
device_revoked |
403 | /v1/devices/renew — caller's cert is in the denylist or device status is revoked |
§9.2.1 |
pem_invalid |
400 | /v1/admin/ssl/* upload — payload is not a parseable PEM cert or key |
§9.2.2 |
cert_key_mismatch |
422 | /v1/admin/ssl/* upload — provided cert and private key do not pair |
§9.2.2 |
regenerate_confirm_required |
409 | /v1/admin/ssl/ca-cert/regenerate — confirm step missing on destructive regenerate |
§9.2.2 |
mtls_not_configured |
503 | Scanner routes when the platform CA is missing — scanner endpoints cannot validate device certs until SSL setup is complete. Admin console endpoints remain reachable. | §9.2.2 |
15.2 Palm Vendor Codes (X-Telcom BioWave Pass)¶
Source: X-Telcom Palm Vein SDK — Large-Scale Comparison Algorithm API.
| Code | Message | Description / Use |
|---|---|---|
0 |
success | Request processed successfully |
10000 |
Parameter Error | Invalid / missing request parameters |
20000 |
Network Error | Transport / network exception |
30001 |
Database Connection Failed | Vendor DB outage |
30002 |
Database Insertion Failed | /KZ/add write failed |
30003 |
Database Deletion Failed | /KZ/delete failed |
30004 |
Database Query Failed | /KZ/query failed |
30005 |
Database Duplicate Insertion | (user_id, palm_type) already registered during /KZ/add |
30006 |
Database ID Not Found | Specified id / user_id does not exist |
30007 |
Database Feature Already Registered | Similar palm already enrolled — potential duplicate / identity fraud (drives §8.10) |
30008 |
Database Query Palm Type Disabled | User has a set_query_type restriction (see §8.11) → mapped to palm_type_restricted |
40000 |
DimPalm Error | Feature-extraction / inference failure |
50000 |
Milvus Error | Vector-DB (1:N search) exception |
No-match is platform-side, not a vendor code. On /KZ/query, BioWave returns code: 0 with scores / thresholds; the platform applies the tenant's palm_match_policy (§8.4) to decide match vs. no-match. There is no dedicated "no results" or "below threshold" error code.
Required header: every Identity → BioWave request includes request_id (UUID) and Content-Type: application/json.
15.3 Nafath Status Codes (KYC — [POST-MVP])¶
KYC integration is [POST-MVP] (§7); these statuses are documented for the future Nafath adapter.
| Status | Description |
|---|---|
| WAITING | User has not responded yet |
| COMPLETED | User approved the request |
| REJECTED | User rejected the request |
| EXPIRED | Request timed out |