Common Issues and Resolutions

This document covers the most frequently encountered issues when integrating with UPBOND Login 3.0 and provides step-by-step solutions.

Authentication Issues

Issue: "Invalid client ID" Error

Error Message:

{
  "error": "invalid_client",
  "error_description": "Client authentication failed"
}

Causes:

• Incorrect client ID in the request

• Client ID not registered with UPBOND

• Client ID disabled or suspended

Resolution:

1. Verify your client ID in the UPBOND dashboard

2. Ensure the client ID matches exactly (case-sensitive)

3. Check if your client is active and not suspended

4. Contact support if the client ID appears correct

Issue: "Redirect URI Mismatch" Error

Error Message:

{
  "error": "redirect_uri_mismatch",
  "error_description": "Invalid redirect URI"
}

Causes:

• Redirect URI not registered in your application settings

• Exact URL mismatch (including protocol, domain, port, path)

• Trailing slash differences

Resolution:

1. Check your registered redirect URIs in the UPBOND dashboard

2. Ensure exact match including:

   • Protocol (http vs https)

   • Domain name

   • Port number

   • Path

   • Query parameters

3. Add the redirect URI to your application settings if missing

Issue: Social Login Provider Errors

Common Provider Errors:

Kakao Login Issues

Error: KOE101 - Invalid client ID

• Solution: Verify Kakao App ID configuration

• Check: Kakao Developer Console settings

WhatsApp Login Issues

Error: WAE102 - Phone number not registered

• Solution: Ensure WhatsApp Business Account is verified

• Check: Meta Business account status

WeChat Login Issues

Error: WCE102 - Unauthorized domain

• Solution: Add your domain to WeChat App settings

• Check: WeChat Developer Console domain whitelist

Telegram Login Issues

Error: TGE102 - Bot not configured for login

• Solution: Configure Telegram Bot with @BotFather

• Check: Bot domain settings

Token Issues

Issue: "Invalid or Expired Token" Error

Error Message:

{
  "error": "invalid_token",
  "error_description": "The access token is invalid or expired"
}

Causes:

• Token has expired

• Token was revoked

• Token format is incorrect

• Clock skew between systems

Resolution:

1. Check token expiration time (exp claim in JWT)

2. Refresh the token using refresh token

3. Verify token format (should be JWT)

4. Synchronize system clocks (NTP)

5. Re-authenticate if refresh fails

Issue: "Insufficient Scope" Error

Error Message:

{
  "error": "insufficient_scope",
  "error_description": "The request requires higher privileges than provided"
}

Causes:

• Token doesn't have required scopes

• Requesting more permissions than granted

• Scope configuration error

Resolution:

1. Check current token scopes:

   curl -H "Authorization: Bearer YOUR_TOKEN" \
        https://auth3.upbond.io/userinfo

2. Request additional scopes during authentication

3. Update application scope configuration

Email and User Management Issues

Issue: Email Verification Not Received

Symptoms:

• User doesn't receive verification email

• Email verification code not working

Causes:

• Email in spam folder

• Email delivery service issues

• Incorrect email address

• Email provider blocking

Resolution:

1. Check spam/junk folder

2. Verify email address spelling

3. Resend verification email:

   curl -X POST "https://auth3.upbond.io/api/v1/users/{userId}/email/resend-verification" \
        -H "Authorization: Bearer YOUR_TOKEN"

4. Try alternative email address

5. Contact support for delivery issues

Issue: Email Change Not Working

Error Message:

{
  "error": "EMAIL_007",
  "error_description": "Password verification failed"
}

Causes:

• Incorrect current password

• Account security restrictions

• Rate limiting

Resolution:

1. Verify current password

2. Check account security status

3. Wait before retry (rate limiting)

4. Use password reset if needed

Device Flow Issues

Issue: Device Code Expired

Error Message:

{
  "error": "expired_token",
  "error_description": "The device code has expired"
}

Causes:

• User took too long to authorize

• Device code timeout (default 30 minutes)

Resolution:

1. Restart device authorization flow

2. Instruct user to complete authorization faster

3. Consider extending timeout in application settings

Issue: User Code Not Recognized

Error Message:

{
  "error": "invalid_request",
  "error_description": "Invalid user code"
}

Causes:

• User entered incorrect code

• Code format confusion (O vs 0, I vs 1)

• Code expired

Resolution:

1. Verify user code format (usually 4-4 character format)

2. Use clear fonts to avoid confusion

3. Provide audio/voice alternative

4. Generate new code if needed

Rate Limiting Issues

Issue: "Too Many Requests" Error

Error Message:

{
  "error": "rate_limit_exceeded",
  "error_description": "Too many requests. Please try again later."
}

Rate Limits:

• Authentication: 60 requests per minute

• Token refresh: 30 requests per minute

• User management: 100 requests per minute

• Email operations: 10 requests per minute

Resolution:

1. Implement exponential backoff

2. Cache tokens to reduce refresh requests

3. Batch operations when possible

4. Contact support for rate limit increase

Network and Connectivity Issues

Issue: "Connection Timeout" Error

Symptoms:

• Requests timing out

• Intermittent connection issues

• Slow response times

Causes:

• Network connectivity issues

• Firewall blocking requests

• DNS resolution problems

• Server overload

Resolution:

1. Check network connectivity

2. Verify firewall settings (allow auth3.upbond.io)

3. Test DNS resolution:

   nslookup auth3.upbond.io

4. Implement retry logic with exponential backoff

5. Check UPBOND status page for service issues

Integration Issues

Issue: CORS (Cross-Origin Resource Sharing) Error

Error Message:

Access to fetch at 'https://auth3.upbond.io/oauth/token' from origin 'https://your-app.com' has been blocked by CORS policy

Causes:

• Browser security restrictions

• Missing CORS configuration

• Incorrect request headers

Resolution:

1. Use proper OAuth flow (Authorization Code with PKCE for SPAs)

2. Don't make token requests from browser (use server-side proxy)

3. For public clients, use implicit flow or authorization code with PKCE

4. Configure CORS settings in UPBOND dashboard

Issue: Mobile App Integration Issues

Common Mobile Issues:

iOS Issues

• App Store Review: Use proper OAuth flows

• Universal Links: Configure associated domains

• Keychain Access: Secure token storage

Android Issues

• Intent Filters: Configure for custom schemes

• Network Security: Allow cleartext traffic for development

• Biometric Authentication: Implement proper fallbacks

Resolution:

1. Follow platform-specific OAuth guidelines

2. Test on multiple devices and OS versions

3. Implement proper error handling

4. Use secure storage for tokens

Performance Issues

Issue: Slow Authentication Response

Symptoms:

• Long authentication times

• Timeouts during login

• Poor user experience

Causes:

• Network latency

• Complex authentication flows

• Server-side processing delays

Resolution:

1. Optimize authentication flow

2. Implement loading indicators

3. Use appropriate timeout values

4. Consider caching strategies

5. Monitor authentication metrics

Debugging Tools

API Testing Tools

Postman Collection: Import the UPBOND Login 3.0 collection for API testing:

https://docs.upbond.io/postman/login-3.0.json

cURL Examples:

# Test authentication endpoint
curl -X POST "https://auth3.upbond.io/oauth/token" \
     -H "Content-Type: application/json" \
     -d '{"grant_type": "client_credentials", "client_id": "YOUR_CLIENT_ID", "client_secret": "YOUR_CLIENT_SECRET"}'

# Test user info endpoint
curl -H "Authorization: Bearer YOUR_TOKEN" \
     "https://auth3.upbond.io/userinfo"

Logging and Monitoring

Enable Debug Logging:

// JavaScript/Node.js
const upbond = require('@upbond/login-3.0');
upbond.setDebug(true);

// Python
import upbond
upbond.debug = True

Monitor Key Metrics:

• Authentication success rate

• Token refresh frequency

• Error rates by type

• Response times

Getting Help

Before Contacting Support

1. Check this troubleshooting guide

2. Review API documentation

3. Test with provided examples

4. Check UPBOND status page

5. Search community forums

Information to Include

When contacting support, provide:

• Error message (exact text)

• Request/response logs

• Client ID (never share client secret)

• Timestamp of issue

• Browser/device information

• Steps to reproduce

Support Channels

• Technical Support: [e-mail]

• Security Issues: [e-mail]

• Community Forum: community.upbond.io

• Status Page: status.upbond.io

• Emergency: [e-mail]

Additional Resources

• API Reference

• SDK Documentation

• Best Practices Guide

• Community Examples