Error Response Format
HTTP Status Codes
| Status | Description |
|---|---|
200 | Success |
201 | Created |
400 | Bad Request - Invalid parameters |
401 | Unauthorized - Invalid API key |
403 | Forbidden - Insufficient permissions |
404 | Not Found - Resource doesn’t exist |
409 | Conflict - Resource already exists |
429 | Too Many Requests - Rate limited |
500 | Server Error - Something went wrong |
Error Types
| Type | Description |
|---|---|
validation_error | Invalid request parameters |
authentication_error | API key issues |
authorization_error | Permission issues |
not_found_error | Resource not found |
rate_limit_error | Rate limit exceeded |
idempotency_error | Idempotency key conflict |
api_error | Internal server error |
Common Error Codes
Authentication Errors
| Code | Description |
|---|---|
unauthorized | Missing or invalid API key |
forbidden | API key lacks required permissions |
key_revoked | API key has been revoked |
ip_not_allowed | Request from non-whitelisted IP |
Validation Errors
| Code | Description |
|---|---|
invalid_request | Request body is malformed |
missing_parameter | Required parameter is missing |
invalid_parameter | Parameter value is invalid |
invalid_document | Document image cannot be processed |
unsupported_country | Country not supported |
unsupported_document | Document type not supported |
Identity Errors
| Code | Description |
|---|---|
document_expired | Document has expired |
document_unreadable | Cannot extract data from document |
face_not_detected | No face found in image |
face_mismatch | Selfie doesn’t match document |
liveness_failed | Liveness check failed |
fraud_detected | Document tampering detected |
Transaction Errors
| Code | Description |
|---|---|
transaction_declined | Transaction was declined |
velocity_exceeded | Rate limit exceeded |
recipient_blocked | Recipient is blocklisted |
amount_exceeded | Amount exceeds limits |
Rate Limit Errors
| Code | Description |
|---|---|
rate_limit_exceeded | Too many requests |
retry_after field: