Members APIAuthentication
Get OTP Status
Check SMS delivery status for OTP verification
POST
/members/me/auth/otp-statusOverview
Unauthenticated endpoint for clients to check if their OTP SMS was delivered successfully. The Inngest handler writes status to Redis as it processes SMS delivery events.
This endpoint helps users understand if delivery issues occurred during the OTP verification flow.
Rate Limiting
- Rate Limit: 30 requests per minute per IP address
- Window: 60 seconds
Request Body
phonebodystringrequiredPhone number in E.164 format (e.g., "+15551234567")
Request
curl -X POST "http://localhost:3000/v1/members/me/auth/otp-status" \
-H "Content-Type: application/json" \
-d '{
"phone": "+15551234567"
}'Response
statusstringrequiredOTP delivery status
Possible values:
"processing"- OTP send is in progress"sent"- OTP was delivered to the provider"failed"- Provider rejected the OTP (fraud, invalid number)"unknown"- No status found (never requested or expired)
messagestringHuman-readable status description
Response
{
"status": "processing",
"message": "OTP delivery is in progress"
}Status Details
Processing
- Meaning: OTP request is still being processed by the SMS provider
- Action: Client should wait and retry after a few seconds
- Duration: Usually resolves within 10-30 seconds
Sent
- Meaning: SMS provider successfully accepted and delivered the message
- Action: Member should receive OTP shortly (if not already received)
- Note: This doesn't guarantee device delivery, only provider acceptance
Failed
- Meaning: SMS provider rejected the message
- Common causes:
- Invalid phone number format
- Number flagged for fraud/spam
- Carrier blocking
- International restrictions
- Action: Member should try a different number or contact support
Unknown
- Meaning: No status record found
- Common causes:
- OTP was never requested for this number
- Status record expired (typically after 1 hour)
- Number format doesn't match request format
- Action: Member should initiate a new OTP request
Usage Flow
- Member requests OTP via Clerk
- Client polls this endpoint to check delivery status
- Based on status, client shows appropriate UI:
- Processing: Show loading state
- Sent: Confirm delivery, proceed to code entry
- Failed: Show error, suggest alternative
- Unknown: Suggest retrying OTP request
Rate Limiting Details
If rate limit is exceeded:
- Returns 429 status code
- Client should implement exponential backoff
- Limit resets after 60 seconds
Related Endpoints
- Validate Auth - Provision member after OTP verification
- Add Verified Contact - Link verified contact
- Get SMS Countries - Check supported countries