OAuth Troubleshooting

Overview

This guide covers common issues you might encounter when implementing OAuth 2.0, along with their solutions and prevention strategies.

Quick Debug Tip: Most OAuth issues fall into one of three categories: PKCE validation, state parameter mismatch, or token confusion. Check these first.

Remember: OAuth troubleshooting is about ensuring users can successfully authorize your application to act on their behalf. Technical issues may prevent users from granting or using the permissions they intend to provide.

Common Errors

invalid_request - Missing required parameters

Error Response:

{
  "error": "invalid_request",
  "error_description": "Missing required parameter: code_challenge"
}

Causes:

Missing PKCE parameters (code_challenge, code_challenge_method)
Missing response_type or incorrect value
Missing state parameter
Missing client_id or redirect_uri

Solutions:

Verify all required parameters are present
Check parameter names match exactly (case-sensitive)
Ensure PKCE parameters use correct encoding (base64url)

Example Fix:

// ❌ Wrong - missing parameters
const params = new URLSearchParams({
  client_id: 'abc123'
});

// ✅ Correct - all required parameters
const params = new URLSearchParams({
  response_type: 'code',
  client_id: 'abc123',
  redirect_uri: 'https://yourapp.com/callback',
  state: generateState(),
  code_challenge: generateCodeChallenge(verifier),
  code_challenge_method: 'S256'
});

invalid_grant - Invalid or expired authorization code

Error Response:

{
  "error": "invalid_grant",
  "error_description": "Authorization code has expired or already been used"
}

Causes:

Authorization code already used (codes are single-use)
Code expired (10-minute lifetime)
Code_verifier doesn’t match code_challenge
Too much time between OAuth steps

Solutions:

Restart OAuth flow from Step 1
Don’t reuse authorization codes
Verify PKCE verifier matches the original challenge
Complete token exchange within 10 minutes

Example Fix:

// ❌ Wrong - reusing code
const tokens1 = await exchangeCode(code, verifier);
const tokens2 = await exchangeCode(code, verifier); // ERROR

// ✅ Correct - use code once
const tokens = await exchangeCode(code, verifier);
// Store tokens, don't exchange again

invalid_client - Authentication failed

Error Response:

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

Causes:

Incorrect x-client-key or x-secret-key
Using sandbox keys in production (or vice versa)
Keys revoked or expired
Missing required headers

Solutions:

Verify both client key and secret key are correct
Ensure you’re using keys for the correct environment
Check headers are named exactly: x-client-key and x-secret-key
Contact support if keys need to be regenerated

Example Fix:

// ❌ Wrong - incorrect header names
headers: {
  'client-key': 'pk_abc123',
  'secret-key': 'sk_xyz789'
}

// ✅ Correct - proper header names
headers: {
  'x-client-key': 'pk_abc123',
  'x-secret-key': 'sk_xyz789'
}

State parameter mismatch

Symptom: Client-side validation fails when comparing state parameters.Causes:

State not stored correctly in session
State modified during OAuth flow
User restored from different session/device
CSRF attack attempt

Solutions:

Store state in secure session storage
Validate state exactly (case-sensitive)
Don’t allow state to be modified
Restart OAuth if state mismatch occurs

Example Fix:

// ❌ Wrong - storing in localStorage (can be modified)
localStorage.setItem('oauth_state', state);

// ✅ Correct - using secure session
sessionStorage.setItem('oauth_state', state);

// Validation
const savedState = sessionStorage.getItem('oauth_state');
if (returnedState !== savedState) {
  // Don't proceed - possible CSRF attack
  throw new Error('State mismatch - please restart login');
}

redirect_uri mismatch

Error Response:

{
  "error": "invalid_request",
  "error_description": "redirect_uri does not match whitelisted URI"
}

Causes:

Redirect URI not whitelisted in environment config
URI doesn’t match exactly (protocol, domain, path)
Trailing slash mismatch
Query parameters in URI

Solutions:

Contact admin to whitelist exact redirect URI
Ensure exact match including protocol (https://)
Don’t include query parameters in redirect_uri
Match trailing slashes exactly

Example Fix:

// ❌ Wrong - different from whitelisted URI
redirect_uri: 'http://app.example.com/callback'  // Missing 's' in https
redirect_uri: 'https://app.example.com/callback/'  // Extra trailing slash
redirect_uri: 'https://app.example.com/auth/callback'  // Different path

// ✅ Correct - exact match
redirect_uri: 'https://app.example.com/callback'

Session expired (10 minutes)

Error Response:

{
  "error": "invalid_grant",
  "error_description": "OAuth session has expired"
}

Causes:

More than 10 minutes between initiation and authorization
User took too long on hosted UI
Network delays or user distraction

Solutions:

Complete OAuth flow within 10 minutes
Display countdown timer to users
Restart flow if session expires
Don’t pre-initiate OAuth too early

Example Fix:

const SESSION_TIMEOUT = 10 * 60 * 1000; // 10 minutes

class OAuthSession {
  private startTime = Date.now();

  isExpired(): boolean {
    return Date.now() - this.startTime >= SESSION_TIMEOUT;
  }

  getRemainingTime(): number {
    return Math.max(0, SESSION_TIMEOUT - (Date.now() - this.startTime));
  }
}

// Show warning when time is running out
if (session.getRemainingTime() < 60000) {
  showWarning('Please complete login within 1 minute');
}

// Restart if expired
if (session.isExpired()) {
  await restartOAuthFlow();
}

Token confusion - Using wrong token type

Symptom: 401 Unauthorized despite having tokens.Causes:

Using JWT token for API calls (should use access token)
Using login access token for final API calls
Mixing up tokens between OAuth steps

Solutions:

JWT Token: Only in Step 3 request body (API mode)
Login Access Token: Only in Step 3 Authorization header (API mode)
Final Access Token: For all subsequent API calls
Refresh Token: Only for token refresh endpoint

Example Fix:

// OAuth Flow Tokens (API Mode)
const { token: jwtToken } = await initiateOAuth();  // Step 1
const loginAccessToken = await login(email, password);  // Step 2

// Step 3: Generate auth code
await fetch('/v1/auth/oauth/authorize', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${loginAccessToken}`,  // Login token in header
  },
  body: JSON.stringify({
    token: jwtToken  // JWT token in body
  })
});

// Step 4: Get final tokens
const { access_token: finalAccessToken } = await exchangeCode(...);

// All subsequent API calls
await fetch('/v1/users/me', {
  headers: {
    'Authorization': `Bearer ${finalAccessToken}`  // Final access token
  }
});

Common Mistake: Using the JWT token from Step 1 for API calls. The JWT is ONLY for OAuth flow coordination.

PKCE validation failed

Error Response:

{
  "error": "invalid_grant",
  "error_description": "Code verifier validation failed"
}

Causes:

code_verifier doesn’t match original code_challenge
Incorrect SHA256 hashing
Base64url encoding issues
Using different verifier than original

Solutions:

Verify SHA256 hash is correctly computed
Use base64url encoding (not standard base64)
Store and retrieve exact same verifier
Check verifier length (43-128 characters)

Example Fix:

// ❌ Wrong - incorrect encoding
function generateChallenge(verifier: string): string {
  return crypto
    .createHash('sha256')
    .update(verifier)
    .digest('base64');  // Wrong - should be base64url
}

// ✅ Correct - base64url encoding
function generateCodeChallenge(verifier: string): string {
  return crypto
    .createHash('sha256')
    .update(verifier)
    .digest('base64url');  // Correct
}

// Verify stored verifier matches
const storedVerifier = sessionStorage.getItem('code_verifier');
if (!storedVerifier) {
  throw new Error('Code verifier not found - restart OAuth flow');
}

OTP required but not provided

Error Response:

{
  "error": "otp_required",
  "message": "User has 2FA enabled",
  "requiresOtp": true
}

Causes:

User has OTP/2FA enabled
OTP code not included in login request

Solutions:

Check login response for requiresOtp field
Call OTP send endpoint to trigger code delivery
Prompt user for OTP code
Retry login with otpCode parameter

Example Fix:

async function handleLogin(email: string, password: string) {
  try {
    const response = await login(email, password);
    return response;
  } catch (error) {
    if (error.requiresOtp) {
      // Send OTP to user
      await sendOTP(email);

      // Prompt user for code
      const otpCode = await promptUserForOTP();

      // Retry with OTP
      return await login(email, password, otpCode);
    }
    throw error;
  }
}

401 after successful token exchange

Symptom: API calls fail with 401 immediately after getting access token.Causes:

Using wrong access token (e.g., login token instead of final token)
Token not being sent in Authorization header
Incorrect Bearer format
Missing x-client-key header

Solutions:

Use access_token from token exchange response
Include in Authorization header as “Bearer ”
Always include x-client-key header
Check for extra spaces or formatting issues

Example Fix:

// Get final tokens
const tokens = await exchangeCodeForTokens(code, verifier);

// ❌ Wrong - various issues
fetch('/v1/users/me', {
  headers: {
    'Authorization': tokens.access_token  // Missing "Bearer"
  }
});

fetch('/v1/users/me', {
  headers: {
    'Authorization': `Bearer ${tokens.access_token}`
    // Missing x-client-key
  }
});

// ✅ Correct - all required headers
fetch('/v1/users/me', {
  headers: {
    'Authorization': `Bearer ${tokens.access_token}`,
    'x-client-key': process.env.CLIENT_KEY
  }
});

Refresh token not working

Error Response:

{
  "error": "invalid_grant",
  "error_description": "Refresh token is invalid or expired"
}

Causes:

Refresh token expired (7 days)
Using old refresh token (tokens rotate)
Token was revoked
Incorrect grant_type parameter

Solutions:

Check refresh token hasn’t expired
Always use the newest refresh token (they rotate)
Clear tokens and re-authenticate if refresh fails
Ensure grant_type is “refresh_token”

Example Fix:

// ❌ Wrong - using old refresh token
const oldToken = getStoredRefreshToken();
const newTokens = await refreshAccessToken(oldToken);
// Still using oldToken next time - ERROR

// ✅ Correct - always update refresh token
const currentToken = getStoredRefreshToken();
const newTokens = await refreshAccessToken(currentToken);

// Update stored token immediately
await storeRefreshToken(newTokens.refresh_token);  // Important!
await storeAccessToken(newTokens.access_token);

// Handle expiration
if (refreshResponse.status === 401) {
  // Refresh token expired - need full re-auth
  await clearAllTokens();
  await redirectToLogin();
}

Debugging Strategies

1. Check Request/Response

Enable Network Logging

Use browser DevTools or a proxy to inspect requests:

// Add logging to your API client
async function apiCall(url: string, options: RequestInit) {
  console.log('Request:', { url, options });

  const response = await fetch(url, options);
  const data = await response.json();

  console.log('Response:', { status: response.status, data });

  return data;
}

Verify Headers

Ensure all required headers are present:

x-client-key: Always required
x-secret-key: Required for OAuth endpoints
Authorization: Required for authenticated endpoints
Content-Type: Required for POST/PUT requests

Check Response Codes

Different status codes indicate different issues:

400: Bad request (missing/invalid parameters)
401: Authentication failed (invalid token/credentials)
403: Forbidden (valid auth, insufficient permissions)
498: Invalid client key
499: Missing client key

2. Validate PKCE Flow

function testPKCE() {
  const verifier = generateCodeVerifier();
  console.log('Verifier:', verifier);
  console.log('Length:', verifier.length); // Should be 43-128

  const challenge = generateCodeChallenge(verifier);
  console.log('Challenge:', challenge);

  // Verify character set
  const validChars = /^[A-Za-z0-9\-._~]+$/;
  console.log('Valid chars:', validChars.test(verifier));

  // Test round-trip
  const testChallenge = generateCodeChallenge(verifier);
  console.log('Matches:', challenge === testChallenge);
}

def test_pkce():
    verifier = generate_code_verifier()
    print(f'Verifier: {verifier}')
    print(f'Length: {len(verifier)}')  # Should be 43-128

    challenge = generate_code_challenge(verifier)
    print(f'Challenge: {challenge}')

    # Verify character set
    import re
    valid_chars = re.match(r'^[A-Za-z0-9\-._~]+$', verifier)
    print(f'Valid chars: {bool(valid_chars)}')

    # Test round-trip
    test_challenge = generate_code_challenge(verifier)
    print(f'Matches: {challenge == test_challenge}')

3. Trace Token Lifecycle

class TokenTracer {
  private events: Array<{ time: Date; event: string; data: any }> = [];

  log(event: string, data: any) {
    this.events.push({
      time: new Date(),
      event,
      data
    });
    console.log(`[${event}]`, data);
  }

  dump() {
    console.table(this.events);
  }
}

const tracer = new TokenTracer();

// Track token flow
tracer.log('OAUTH_INIT', { jwtToken: jwt.substring(0, 20) });
tracer.log('LOGIN', { accessToken: token.substring(0, 20) });
tracer.log('AUTH_CODE', { code: code.substring(0, 20) });
tracer.log('TOKEN_EXCHANGE', {
  accessToken: tokens.access_token.substring(0, 20),
  refreshToken: tokens.refresh_token.substring(0, 20)
});

// Review trace
tracer.dump();

from datetime import datetime
from typing import Any, Dict, List

class TokenTracer:
    def __init__(self):
        self.events: List[Dict[str, Any]] = []

    def log(self, event: str, data: Any):
        self.events.append({
            'time': datetime.now(),
            'event': event,
            'data': data
        })
        print(f'[{event}]', data)

    def dump(self):
        for event in self.events:
            print(f"{event['time']}: {event['event']} - {event['data']}")

tracer = TokenTracer()

# Track token flow
tracer.log('OAUTH_INIT', {'jwtToken': jwt[:20]})
tracer.log('LOGIN', {'accessToken': token[:20]})
tracer.log('AUTH_CODE', {'code': code[:20]})
tracer.log('TOKEN_EXCHANGE', {
    'accessToken': tokens['access_token'][:20],
    'refreshToken': tokens['refresh_token'][:20]
})

# Review trace
tracer.dump()

Environment-Specific Issues

Sandbox vs Production

Sandbox Issues

HTTP allowed in sandbox only
Different client keys per environment
Sandbox data doesn’t transfer to production
Rate limits may differ

Production Issues

HTTPS strictly required
Redirect URIs must be whitelisted
More strict validation
Lower tolerance for errors

Regional Routing

If using US environment:

// Add x-us-env header for US routing
headers: {
  'x-client-key': process.env.CLIENT_KEY,
  'x-us-env': 'true'  // Required for US environment
}

Prevention Best Practices

1. Implement Comprehensive Error Handling

class OAuthError extends Error {
  constructor(
    public code: string,
    public description: string,
    public statusCode: number
  ) {
    super(description);
  }
}

async function handleOAuthError(response: Response) {
  const error = await response.json();

  switch (error.error) {
    case 'invalid_grant':
      // Restart OAuth flow
      await clearOAuthState();
      throw new OAuthError(
        error.error,
        'Authorization expired. Please login again.',
        response.status
      );

    case 'invalid_client':
      // Configuration issue
      logCritical('Invalid OAuth credentials');
      throw new OAuthError(
        error.error,
        'Authentication configuration error. Please contact support.',
        response.status
      );

    case 'invalid_request':
      // Developer error
      logError('OAuth request invalid', error);
      throw new OAuthError(
        error.error,
        error.error_description || 'Invalid request',
        response.status
      );

    default:
      throw new OAuthError(
        error.error || 'unknown_error',
        error.error_description || 'An unexpected error occurred',
        response.status
      );
  }
}

class OAuthError(Exception):
    def __init__(self, code: str, description: str, status_code: int):
        self.code = code
        self.description = description
        self.status_code = status_code
        super().__init__(description)

def handle_oauth_error(response: requests.Response):
    error = response.json()
    error_code = error.get('error', 'unknown_error')

    if error_code == 'invalid_grant':
        # Restart OAuth flow
        clear_oauth_state()
        raise OAuthError(
            error_code,
            'Authorization expired. Please login again.',
            response.status_code
        )
    elif error_code == 'invalid_client':
        # Configuration issue
        log_critical('Invalid OAuth credentials')
        raise OAuthError(
            error_code,
            'Authentication configuration error. Please contact support.',
            response.status_code
        )
    elif error_code == 'invalid_request':
        # Developer error
        log_error('OAuth request invalid', error)
        raise OAuthError(
            error_code,
            error.get('error_description', 'Invalid request'),
            response.status_code
        )
    else:
        raise OAuthError(
            error_code,
            error.get('error_description', 'An unexpected error occurred'),
            response.status_code
        )

2. Add Validation Checks

function validateOAuthState() {
  const checks = [
    {
      name: 'Code Verifier',
      test: () => {
        const verifier = getCodeVerifier();
        return verifier && verifier.length >= 43 && verifier.length <= 128;
      }
    },
    {
      name: 'State Parameter',
      test: () => {
        const state = getState();
        return state && state.length >= 16;
      }
    },
    {
      name: 'Redirect URI',
      test: () => {
        const uri = getRedirectUri();
        return uri && uri.startsWith('https://');
      }
    }
  ];

  const failed = checks.filter(check => !check.test());

  if (failed.length > 0) {
    console.error('Validation failed:', failed.map(f => f.name));
    return false;
  }

  return true;
}

3. Set Up Monitoring

// Track OAuth success/failure rates
function trackOAuthMetric(event: string, success: boolean, error?: string) {
  analytics.track('OAuth Event', {
    event,
    success,
    error,
    timestamp: Date.now(),
    environment: process.env.NODE_ENV
  });
}

// Usage
try {
  await initiateOAuth();
  trackOAuthMetric('initiate', true);
} catch (error) {
  trackOAuthMetric('initiate', false, error.message);
}

Testing Tools

OAuth Flow Tester

import { describe, it, expect } from 'vitest';

describe('OAuth Flow', () => {
  it('generates valid PKCE parameters', () => {
    const verifier = generateCodeVerifier();
    expect(verifier.length).toBeGreaterThanOrEqual(43);
    expect(verifier.length).toBeLessThanOrEqual(128);
    expect(verifier).toMatch(/^[A-Za-z0-9\-._~]+$/);

    const challenge = generateCodeChallenge(verifier);
    expect(challenge).toBeDefined();
    expect(challenge.length).toBeGreaterThan(0);
  });

  it('validates state parameter', () => {
    const state = generateState();
    expect(state.length).toBeGreaterThanOrEqual(16);
  });

  it('handles token refresh correctly', async () => {
    const tokens = await refreshAccessToken('valid_refresh_token');
    expect(tokens.access_token).toBeDefined();
    expect(tokens.refresh_token).toBeDefined();
  });
});

import pytest

def test_pkce_generation():
    verifier = generate_code_verifier()
    assert len(verifier) >= 43
    assert len(verifier) <= 128

    import re
    assert re.match(r'^[A-Za-z0-9\-._~]+$', verifier)

    challenge = generate_code_challenge(verifier)
    assert challenge
    assert len(challenge) > 0

def test_state_generation():
    state = generate_state()
    assert len(state) >= 16

@pytest.mark.asyncio
async def test_token_refresh():
    tokens = await refresh_access_token('valid_refresh_token')
    assert 'access_token' in tokens
    assert 'refresh_token' in tokens

Getting Additional Help

Check API Status

Verify there are no ongoing incidents or maintenance:

Check status page
Review error rates in dashboard
Confirm environment availability

Review Logs

Enable detailed logging to capture:

Request/response bodies
Header values (sanitize secrets!)
Timing information
Error stack traces

Contact Support

When contacting support, include:

Error messages and codes
Request/response examples (sanitized)
Environment (sandbox/production)
Approximate timestamp of issues
Client key (NOT secret key)

Community Resources

Get help from the community:

Search documentation
Review example implementations
Check for similar issues
Share non-sensitive code samples

Quick Reference

OAuth Error Codes

Error Code	Meaning	Typical Cause	Solution
`invalid_request`	Missing/invalid params	Incorrect API call	Check all required parameters
`invalid_grant`	Code invalid/expired	Used code twice or expired	Restart OAuth flow
`invalid_client`	Auth failed	Wrong keys	Verify client credentials
`access_denied`	User denied	User clicked deny	Expected behavior, handle gracefully
`unauthorized_client`	Client not authorized	OAuth not enabled	Contact administrator

HTTP Status Codes

Code	Meaning	Action
`400`	Bad Request	Check request parameters
`401`	Unauthorized	Check authentication tokens
`403`	Forbidden	Check permissions/scope
`404`	Not Found	Check endpoint URL
`498`	Invalid Client Key	Verify x-client-key header
`499`	Missing Client Key	Add x-client-key header
`500`	Server Error	Retry or contact support

Next Steps

OAuth Quick Start

Start implementing OAuth from scratch

Security Best Practices

Review security guidelines

Token Management

Master token lifecycle

API Reference

Detailed endpoint documentation

Getting Started

OAuth

Wallets

Delegation

Card Operations

Consent

Webhooks

OAuth Troubleshooting

Overview

Common Errors

Debugging Strategies

1. Check Request/Response

2. Validate PKCE Flow

3. Trace Token Lifecycle

Environment-Specific Issues

Sandbox vs Production

Sandbox Issues

Production Issues

Regional Routing

Prevention Best Practices

1. Implement Comprehensive Error Handling

2. Add Validation Checks

3. Set Up Monitoring

Testing Tools

OAuth Flow Tester

Getting Additional Help

Check API Status

Review Logs

Contact Support

Community Resources

Quick Reference

OAuth Error Codes

HTTP Status Codes

Next Steps

OAuth Quick Start

Security Best Practices

Token Management

API Reference

​Overview

​Common Errors

​Debugging Strategies

​1. Check Request/Response

​2. Validate PKCE Flow

​3. Trace Token Lifecycle

​Environment-Specific Issues

​Sandbox vs Production

Sandbox Issues

Production Issues

​Regional Routing

​Prevention Best Practices

​1. Implement Comprehensive Error Handling

​2. Add Validation Checks

​3. Set Up Monitoring

​Testing Tools

​OAuth Flow Tester

​Getting Additional Help

Check API Status

Review Logs

Contact Support

Community Resources

​Quick Reference

​OAuth Error Codes

​HTTP Status Codes

​Next Steps

OAuth Quick Start

Security Best Practices

Token Management

API Reference

Overview

Common Errors

Debugging Strategies

1. Check Request/Response

2. Validate PKCE Flow

3. Trace Token Lifecycle

Environment-Specific Issues

Sandbox vs Production

Regional Routing

Prevention Best Practices

1. Implement Comprehensive Error Handling

2. Add Validation Checks

3. Set Up Monitoring

Testing Tools

OAuth Flow Tester

Getting Additional Help

Quick Reference

OAuth Error Codes

HTTP Status Codes

Next Steps