Troubleshooting

Common issues, error scenarios, and solutions.

API Issues

401 Unauthorized

Symptom: All API requests return 401 Unauthorized.

Causes:

• Missing Authorization header
• Invalid or expired API token
• Token has been revoked

Solutions:

• Verify the Authorization: Bearer {token} header is present
• Generate a new token from the dashboard
• Check that the token hasn't expired (default: 180 days)
• Ensure you are using the correct workspace URL

404 Not Found

Symptom: API requests return 404 Not Found.

Causes:

• Incorrect resource ID
• Resource belongs to a different workspace
• Wrong API version in the URL
• Wrong flow path name

Solutions:

• Verify the resource ID is correct
• Confirm the resource belongs to your workspace
• Check the API URL format: /api/v1/{flow}/{resource}
• Use the correct flow path: usps1583 or identity

422 Validation Error

Symptom: API requests return 422 Unprocessable Entity with validation errors.

Causes:

• Missing required fields
• Invalid field values (wrong type, format, or length)
• Invalid document type for the flow
• Forbidden document type + country combination
• Document types are the same for photo ID and proof of address

Solutions:

• Inspect the errors object in the response for specific field messages
• Verify document types exist in the flow configuration
• Check for forbidden document type + country combinations
• Ensure photo ID and proof of address document types differ

400 Bad Request (Invalid Flow)

Symptom: Requests return 400 Bad Request with "Invalid verification flow.".

Causes:

• The verification does not belong to the specified flow
• Wrong flow path in the URL

Solutions:

• Check the verification's flow membership
• Use the correct flow path in the URL

400 Bad Request (Business Rules)

Symptom: Requests return 400 Bad Request with business rule error messages.

Common Error Messages:

Error	Cause	Solution
The verification is canceled.	Attempting to modify a canceled verification	Create a new verification
The verification has already started.	Attempting to upload documents after submission	The verification is already in the pipeline
Document type not allowed.	Document type is not configured for this flow	Check the flow's document type configuration
The verification already has a {type} document.	Duplicate document type upload	Delete the existing document first
The document is canceled.	Attempting to make a decision on a canceled document	The document is no longer active
The document could not be created by missing data...	Missing required data	Check request body for completeness

---

Authentication Issues

MFA OTP Not Received

Symptom: You log in but do not receive the MFA OTP email.

Causes:

• Email sent to spam/junk folder
• Incorrect email address on the account
• Email server delay

Solutions:

• Check your spam/junk folder
• Wait a few minutes and request a new code
• Contact an administrator to verify your email address
• An administrator can reset your MFA if needed

Account Locked

Symptom: You cannot log in and see a lockout message.

Causes:

• Multiple failed login attempts
• Brute force protection triggered

Solutions:

• Wait for the lockout period to expire
• Contact an administrator to unlock your account manually

Cannot Complete MFA

Symptom: You cannot access the MFA challenge page.

Causes:

• MFA challenge session has expired
• You navigated away from the challenge page

Solutions:

• Log in again to receive a new MFA challenge
• If the problem persists, contact an administrator

---

Verification Processing Issues

Verification Stuck in "Started"

Symptom: A verification remains in Started status for an extended period.

Causes:

• Documents not uploaded
• Verification not submitted
• Required documents missing

Solutions:

• Upload all required documents (photo ID, proof of address)
• Submit the verification using the submit endpoint
• Check the flow configuration for required document types

Verification Stuck in "Submitted"

Symptom: A verification remains in Submitted status without progressing.

Causes:

• Extraction pipeline is processing
• Queue backlog
• Extraction failure

Solutions:

• Wait a few minutes for processing to complete
• Check the verification documents for extraction errors
• Contact support if the issue persists

Data Extraction Failed

Symptom: Document processing fails or returns empty extracted data.

Causes:

• Low-quality document image
• Unsupported document format
• Extraction provider error

Solutions:

• Upload a higher-quality image (better lighting, higher resolution)
• Ensure the document is a supported type
• Try a different document type

Selfie Match Failed

Symptom: The selfie comparison score is low or the rule fails.

Causes:

• Poor lighting during selfie capture
• Face not clearly visible
• Different person than the photo ID

Solutions:

• Retake the selfie in even lighting
• Ensure the entire face is visible
• Remove sunglasses, masks, or other obstructions

---

Webhook Issues

Webhook Not Received

Symptom: Your endpoint never receives webhook requests.

Causes:

• Webhook is inactive
• URL is incorrect
• Network connectivity issues
• Event not selected
• The verification is in Double Check status

Solutions:

• Verify the webhook is active in the dashboard
• Check the URL is correct and accessible from the internet
• Verify the events you want are selected
• Check the Webhooks logs for delivery attempts
• If expecting verification.finished, confirm the verification is not in Double Check

Webhook Delivery Failed

Symptom: Webhook logs show failed delivery attempts.

Causes:

• Endpoint returns non-2xx response
• Endpoint timeout (10-second limit)
• SSL certificate verification failure
• DNS resolution failure
• Network connectivity issues

Solutions:

• Check your endpoint logs for errors
• Ensure your endpoint responds within the 10-second timeout
• Verify your SSL certificate is valid and chained to a public CA
• Check DNS configuration

Use the Resend option in the webhook logs to retry after fixing the issue and mark the log entry as Solved once the root cause is addressed. See Webhooks Delivery for full details on retry logic and delivery.

Invalid Webhook Signature

Symptom: You cannot verify the webhook signature.

Causes:

• Using the wrong signing secret
• Payload encoding mismatch (using parsed JSON instead of raw body)
• Request body was modified during transmission
• Using the wrong comparison method (non-constant-time comparison)

Solutions:

• Use the exact signing secret shown when the webhook was created. If lost, delete and recreate the webhook
• Capture the raw request body before any JSON parsing — re-serializing JSON changes the byte sequence
• Use hex-encoded HMAC-SHA256 (not base64)
• Use a constant-time comparison function (hash_equals in PHP, timingSafeEqual in Node.js, hmac.compare_digest in Python, Rack::Utils.secure_compare in Ruby)

For verification code examples in multiple languages and a test vector, see Verifying Signatures.

Webhook Endpoint Timing Out

Symptom: Webhook deliveries consistently fail with timeout errors.

Causes:

• Endpoint takes longer than 10 seconds to respond
• Slow database queries or external API calls in the handler
• Insufficient server resources

Solutions:

• Move long-running operations to a background job queue
• Return a 2xx response immediately and process asynchronously
• Optimize your endpoint to respond within 10 seconds
• Check your server's CPU and memory usage during webhook bursts

Webhook Returning 4xx/5xx

Symptom: Webhook logs show non-2xx status codes from your endpoint.

Causes:

• Application error in your webhook handler
• Authentication header missing or invalid
• Route not configured for the webhook URL

Solutions:

• Check your application logs for the specific error
• Verify the authentication header configured in the webhook matches your endpoint's expectations
• Ensure the webhook URL path is correctly routed in your application

---

Document Issues

Document Rejected

Symptom: A document is rejected by the validation pipeline.

Common Rejection Reasons:

Issue	Solution
Name mismatch	Upload a document with the correct name
Country mismatch	Check the document's issuing country
Document type mismatch	Select the correct document type
Document number mismatch	Verify the document number
Date of birth mismatch	Upload a document with matching DOB
Document expired	Upload a valid (non-expired) document
Address is blacklisted	Use a different address
Selfie mismatch	Retake the selfie with better lighting

Cannot Upload Document

Symptom: Document upload fails with an error.

Common Causes:

• Verification is already submitted (status is not Started)
• Verification is canceled
• Duplicate document type (already uploaded)
• Document type not allowed for the flow
• Image too large (over 10 MB)

Solutions:

• Check the verification status — documents can only be uploaded when in Started status
• Verify the document type is configured for the flow
• Delete the existing document of the same type if replacing
• Compress the image to under 10 MB

---

Rate Limiting

429 Too Many Requests

Symptom: Requests return 429 Too Many Requests.

Causes:

• Exceeded the rate limit for your workspace

Solutions:

• Wait for the Retry-After period before making additional requests
• Implement exponential backoff in your application
• Reduce the frequency of polling requests

---

Permission Issues

403 Forbidden

Symptom: Dashboard actions or API requests return 403 Forbidden.

Causes:

• Your role does not have the required permission
• You are trying to access a resource in a different workspace

Solutions:

• Contact an administrator to check your role permissions
• Verify you are in the correct workspace
• Request role elevation if needed for your tasks

---

Environment Issues

Sandbox vs Production Differences

Symptom: Behavior differs between sandbox and production.

Common Differences:

• MFA is enforced in production but may be disabled in sandbox
• Extraction providers may behave differently with test data

Solutions:

• Use realistic test data in the sandbox for accurate results
• Note that MFA enforcement is a production security requirement
• Contact support if you notice significant behavioral differences

---

Getting Help

If you encounter an issue not covered here:

1. Check the webhook logs and activity logs for detailed error information
2. Review the verification history for the affected resource
3. Contact our support team with:
   • The workspace name
   • The resource ID (verification, document, etc.)
   • The timestamp of the issue
   • Any error messages or response codes