Error Code Reference

Error Response Format

All errors follow RFC 7807 Problem Details for HTTP APIs:

{
  "type": "urn:org:hopae:problem-type:client/100001",
  "title": "AUTH.INVALID_CREDENTIALS",
  "status": 401,
  "detail": "Invalid client credentials provided",
  "instance": "/api/oauth/token",
  "code": 100001,
  "timestamp": "2024-01-20T10:30:00.000Z",
  "context": {
    "client_id": "example_client"
  }
}

Error Code Structure

Error codes follow a domain-based structure:

Format: DXXXXX (Domain + 5 digits)
Domains:
- 1xxxxx - Authentication errors
- 2xxxxx - Validation errors
- 3xxxxx - Session management errors
- 4xxxxx - Provider-specific errors
- 5xxxxx - System errors

Authentication Errors

Invalid Credentials

error

Code: 100001
HTTP Status: 401Invalid client credentials (Client ID or Client Secret incorrect)Common Causes:

Wrong Client ID or Client Secret
Using sandbox credentials in production or vice versa
Credentials have been rotated

Invalid Grant

error

Code: 100002
HTTP Status: 400Invalid grant provided (OAuth2 standard error)Common Causes:

Authorization code has expired
Authorization code has been used already
Code verifier mismatch in PKCE flow

Invalid Client

error

Code: 100003
HTTP Status: 401Client authentication failed (OAuth2 standard error)Common Causes:

Client doesn’t exist
Client is disabled
Authentication method not allowed for client

Validation Errors

Missing Parameter

error

Code: 200001
HTTP Status: 400Required parameter is missing from the requestCommon Causes:

Missing required query parameters
Missing required body fields
Empty request body

Invalid Parameter

error

Code: 200002
HTTP Status: 400Parameter value is invalidCommon Causes:

Invalid format (e.g., email, URL)
Value out of allowed range
Unsupported parameter value

Missing User Data

error

Code: 200003
HTTP Status: 400Required user data is missingCommon Causes:

Provider didn’t return required attributes
User didn’t consent to required scopes

Invalid User Data

error

Code: 200004
HTTP Status: 400User data format is invalidCommon Causes:

Malformed data from provider
Data validation failed

Invalid PKCE

error

Code: 200005
HTTP Status: 400Invalid PKCE parametersCommon Causes:

Missing code challenge
Invalid code verifier format
Code verifier doesn’t match challenge

Redirect URI Required

error

Code: 200006
HTTP Status: 400Redirect URI is required but not providedCommon Causes:

No default redirect URI configured
Public client without redirect URI

Missing Client Secret

error

Code: 200007
HTTP Status: 400Client secret is required but not providedCommon Causes:

Confidential client authenticating without secret
Wrong authentication method used

Session Management Errors

Session Not Found

error

Code: 300001
HTTP Status: 404Session does not existCommon Causes:

Invalid session ID
Session has expired
Session was deleted

Verification Not Found

error

Code: 300002
HTTP Status: 404Verification session not foundCommon Causes:

Invalid verification ID
Verification has expired
Wrong environment (sandbox vs production)

Invalid Status Transition

error

Code: 300003
HTTP Status: 409Invalid session status transitionCommon Causes:

Session already completed
Session was cancelled
Attempting invalid state change

Invalid Flow

error

Code: 300004
HTTP Status: 400Invalid verification flowCommon Causes:

Unsupported flow type for provider
Flow parameters are invalid
Flow not enabled for application

Provider Errors

Provider Not Found

error

Code: 400001
HTTP Status: 404Provider not foundCommon Causes:

Invalid provider ID
Provider not available in region
Typo in provider identifier

Provider Not Enabled

error

Code: 400002
HTTP Status: 403Provider is not enabled for this applicationCommon Causes:

Provider not configured in dashboard
Provider disabled for maintenance
Account doesn’t have access to provider

Initialization Failed

error

Code: 400003
HTTP Status: 502Provider initialization failedCommon Causes:

Provider service is down
Network connectivity issues
Invalid provider configuration

Provider Error

error

Code: 400004
HTTP Status: 502Generic provider errorCommon Causes:

Provider returned an error
Provider timeout
Unexpected provider response

Provider Unavailable

error

Code: 400005
HTTP Status: 503Provider service is unavailableCommon Causes:

Provider maintenance
Provider service outage
Rate limited by provider

System Errors

Internal Error

error

Code: 500001
HTTP Status: 500Internal server errorCommon Causes:

Unexpected system error
Database connection issues
Configuration errors

Action: Contact support if persists

Unsupported Mode

error

Code: 500002
HTTP Status: 501Requested mode or feature is not supportedCommon Causes:

Feature not implemented
Deprecated functionality
Invalid operation mode

Error Categories

Errors are categorized for proper handling:

Category	HTTP Status Range	Description	Retry Strategy
`client`	400-499	Client errors	Do not retry automatically
`failure`	502-503	External service failures	Retry with exponential backoff
`error`	500-501	System errors	Retry once after delay

Error Handling Best Practices

Retry Strategy

// Errors that can be retried
const RETRYABLE_CODES = [
  400003, // INITIALIZATION_FAILED
  400004, // PROVIDER_ERROR  
  400005, // PROVIDER_UNAVAILABLE
  500001, // INTERNAL_ERROR
];

// Implement exponential backoff
async function retryWithBackoff(fn, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await fn();
    } catch (error) {
      if (!RETRYABLE_CODES.includes(error.code)) {
        throw error;
      }
      if (i === maxRetries - 1) throw error;
      
      const delay = Math.min(1000 * Math.pow(2, i), 10000);
      await new Promise(resolve => setTimeout(resolve, delay));
    }
  }
}

User Communication

Error Code	User-Friendly Message
`100001`	”Authentication failed. Please check your credentials.”
`200001`	”Some required information is missing. Please try again.”
`300001`	”Your session has expired. Please start over.”
`300003`	”This verification has already been completed.”
`400002`	”This identity provider is not available.”
`400005`	”The identity service is temporarily unavailable. Please try again later.”
`500001`	”Something went wrong on our end. Please try again.”

Error Context

Always include relevant context when logging errors:

function logError(error, context) {
  console.error({
    code: error.code,
    title: error.title,
    detail: error.detail,
    timestamp: error.timestamp,
    // Application context
    verificationId: context.verificationId,
    userId: context.userId,
    provider: context.provider,
    environment: process.env.NODE_ENV,
    // Never log sensitive data
    // ❌ accessToken, clientSecret, userData
  });
}

Support

For persistent errors or issues not covered here:

Developer Support

Email: dev@hopae.comInclude in your report:

Error code
Timestamp
Verification ID (if available)
Environment (Sandbox/Production)
Request ID from headers

API Reference

Providers

Verifications

Token

Error Code Reference

Error Response Format

Error Code Structure

Authentication Errors

Validation Errors

Session Management Errors

Provider Errors

System Errors

Error Categories

Error Handling Best Practices

Retry Strategy

User Communication

Error Context

Support

Developer Support

API Reference

Providers

Verifications

Token

​Error Response Format

​Error Code Structure

​Authentication Errors

​Validation Errors

​Session Management Errors

​Provider Errors

​System Errors

​Error Categories

​Error Handling Best Practices

​Retry Strategy

​User Communication

​Error Context

​Support

Developer Support

Error Response Format

Error Code Structure

Authentication Errors

Validation Errors

Session Management Errors

Provider Errors

System Errors

Error Categories

Error Handling Best Practices

Retry Strategy

User Communication

Error Context

Support