Overview
The otp.failed event is triggered when an OTP delivery attempt fails. This event includes error details and a resend endpoint for retrying the OTP delivery.
Example Payload
{
"eventType": "otp.failed",
"requestId": "68c6b2c3d4e5f6789012345",
"issuerDid": "did:via:org-abc123",
"user": {
"contact": "+1234567890",
"did": "did:via:user-xyz789",
"internalId": "user_otp_001"
},
"decisionDate": "2024-01-15T22:45:00.000Z",
"otp": {
"resendEndpoint": "/v1/requests/68c6b2c3d4e5f6789012345/resend",
"error": {
"code": "INVALID_PHONE_NUMBER",
"message": "The phone number format is invalid for the selected country"
}
}
}
Base Fields
All OTP failed events include these common fields:
| Field | Type | Required | Description |
|---|
eventType | string | Yes | Always "otp.failed" |
requestId | string | Yes | Request identifier |
internalId | string | No | Your internal identifier for the request |
issuerDid | string | Yes | DID of the organization/issuer |
user | object | Yes | Object containing user identity fields |
decisionDate | Date | Yes | Timestamp when the OTP failure was recorded |
User Object
| Field | Type | Required | Description |
|---|
contact | string | Yes | Contact that failed (phone number or email) |
did | string | Yes | DID of the user/subject |
internalId | string | No | Your internal identifier for the user |
OTP Object
The otp field contains failure details and retry information:
| Field | Type | Required | Description |
|---|
resendEndpoint | string | Yes | API endpoint to resend the OTP |
error | object | Yes | Error details |
Error Object
The error field contains details about why the OTP delivery failed:
| Field | Type | Required | Description |
|---|
code | string | Yes | Specific error code indicating the failure reason |
message | string | Yes | Human-readable error message |
Common Error Codes
| Code | Description |
|---|
INVALID_PHONE_NUMBER | Phone number format is invalid |
UNDELIVERABLE | Message could not be delivered to the carrier |
CARRIER_REJECTED | Carrier rejected the message |
RATE_LIMITED | Too many attempts, rate limit exceeded |
BLOCKED_DESTINATION | Destination is blocked or blacklisted |
INVALID_EMAIL | Email address format is invalid |
EMAIL_BOUNCED | Email bounced back |
SPAM_DETECTED | Message was flagged as spam |
Handling OTP Failures
When you receive an otp.failed event:
- Log the error - Record the
error.code and error.message for debugging
- Notify the user - Inform the user about the delivery failure and provide options
- Retry if appropriate - Use the
otp.resendEndpoint to attempt OTP delivery again
Resending OTP
To retry OTP delivery, make a POST request to the otp.resendEndpoint:
curl -X POST https://api.humanos.id/v1/requests/68c6b2c3d4e5f6789012345/resend \
-H "Authorization: Bearer YOUR_API_KEY"
The resend endpoint may have rate limiting. Check the response headers for
X-RateLimit-Remaining before retrying.
