Error Code Reference

Error Response Format

All errors follow RFC 7807 Problem Details for HTTP APIs:

{
  "title": "AUTH_INVALID_CREDENTIALS",
  "status": 401,
  "detail": "Invalid client credentials provided",
  "instance": "/token",
  "timestamp": "2024-01-20T10:30:00.000Z",
  "context": {
    "client_id": "example_client"
  },
  "doc_url": "https://docs.hopae.com/api-reference/error-codes#invalid-credentials"
}

Response Fields

Field	Type	Description
`title`	string	Error code identifier (e.g., `AUTH_INVALID_CREDENTIALS`)
`status`	number	HTTP status code
`detail`	string	Human-readable error description
`instance`	string	The request path where the error occurred
`timestamp`	string	ISO 8601 timestamp of when the error occurred
`context`	object	Additional context information (optional)
`doc_url`	string	Link to documentation for this error (optional)

Error Code Structure

Error codes follow a string-based, domain-prefixed structure:

Format: CATEGORY_ERROR_NAME
Categories:
- AUTH_* - Authentication errors
- VALIDATION_* - Validation errors
- SESSION_* - Session management errors
- PROVIDER_* - Provider-specific errors
- SYSTEM_* - System errors
- RESOURCE_* - Resource errors

Authentication Errors

Invalid Credentials

error

Code: AUTH_INVALID_CREDENTIALS 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: AUTH_INVALID_GRANT HTTP Status: 400Invalid grant provided (OAuth2 standard error)Common Causes:

Authorization code has expired
Authorization code has been used already

Invalid Client

error

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

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

Forbidden

error

Code: AUTH_FORBIDDEN HTTP Status: 403Access denied. The authenticated user does not have permission to access the requested resource.Common Causes:

Unauthorized origin attempting access
Insufficient permissions for the resource
Action not allowed for the authenticated client

Example Response:

{
  "title": "AUTH_FORBIDDEN",
  "status": 403,
  "detail": "Access denied",
  "instance": "/apps/client_abc123",
  "timestamp": "2024-01-20T10:30:00.000Z",
  "context": {
    "reason": "Unauthorized origin",
    "resource": "app",
    "action": "read"
  }
}

Validation Errors

Missing Parameter

error

Code: VALIDATION_MISSING_PARAMETER 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: VALIDATION_INVALID_PARAMETER 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: VALIDATION_MISSING_USER_DATA 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: VALIDATION_INVALID_USER_DATA HTTP Status: 400User data format is invalidCommon Causes:

Malformed data from provider
Data validation failed

Redirect URI Required

error

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

No default redirect URI configured
Public client without redirect URI

Session Management Errors

Session Not Found

error

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

Invalid session ID
Session has expired
Session was deleted

Verification Not Found

error

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

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

Invalid Status Transition

error

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

Session already completed
Session was cancelled
Attempting invalid state change

Invalid Flow

error

Code: SESSION_INVALID_FLOW 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: PROVIDER_NOT_FOUND HTTP Status: 404Provider not foundCommon Causes:

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

Provider Not Enabled

error

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

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

Initialization Failed

error

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

Provider service is down
Network connectivity issues
Invalid provider configuration

Provider Error

error

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

Provider returned an error
Provider timeout
Unexpected provider response

Provider Unavailable

error

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

Provider maintenance
Provider service outage
Rate limited by provider

Provider Configuration Error

error

Code: PROVIDER_CONFIGURATION_ERROR HTTP Status: 400The provider configuration is invalid or incomplete.Common Causes:

Missing required configuration values
Invalid configuration format
Incomplete provider setup

Example Response:

{
  "title": "PROVIDER_CONFIGURATION_ERROR",
  "status": 400,
  "detail": "Missing configuration 'apiSecret' for pass",
  "instance": "/verifications",
  "timestamp": "2024-01-20T10:30:00.000Z",
  "context": {
    "providerId": "pass",
    "missingConfig": "apiSecret"
  }
}

Provider Authentication Failed

error

Code: PROVIDER_AUTHENTICATION_FAILED HTTP Status: 401Authentication with the eID provider failed.Common Causes:

Invalid provider credentials
Provider API key expired
Authentication token invalid

Example Response:

{
  "title": "PROVIDER_AUTHENTICATION_FAILED",
  "status": 401,
  "detail": "Failed to initiate iPIN authentication: Invalid credentials",
  "instance": "/verifications",
  "timestamp": "2024-01-20T10:30:00.000Z",
  "context": {
    "providerId": "ipin"
  }
}

Provider Unexpected Response

error

Code: PROVIDER_UNEXPECTED_RESPONSE HTTP Status: 502The provider returned an unexpected or invalid response.Common Causes:

Empty response from provider
Malformed response data
Unexpected response format

Example Response:

{
  "title": "PROVIDER_UNEXPECTED_RESPONSE",
  "status": 502,
  "detail": "Empty response from identity verification",
  "instance": "/verifications",
  "timestamp": "2024-01-20T10:30:00.000Z",
  "context": {
    "providerId": "pass"
  }
}

System Errors

Internal Error

error

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

Unexpected system error
Database connection issues
Configuration errors

Action: Contact support if persists

Unsupported Mode

error

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

Feature not implemented
Deprecated functionality
Invalid operation mode

Resource Errors

Generic resource errors for CRUD operations.

Resource Not Found

error

Code: RESOURCE_NOT_FOUND HTTP Status: 404The requested resource was not found.Common Causes:

Invalid resource identifier
Resource has been deleted
Resource does not exist

Example Response:

{
  "title": "RESOURCE_NOT_FOUND",
  "status": 404,
  "detail": "App not found",
  "instance": "/apps/client_abc123",
  "timestamp": "2024-01-20T10:30:00.000Z",
  "context": {
    "resource": "App",
    "identifier": "client_abc123"
  }
}

Resource Conflict

error

Code: RESOURCE_CONFLICT HTTP Status: 409A conflict occurred with the current state of the resource (e.g., duplicate entry).Common Causes:

Resource already exists with the same identifier
Duplicate entry attempt
Concurrent modification conflict

Example Response:

{
  "title": "RESOURCE_CONFLICT",
  "status": 409,
  "detail": "App already exists",
  "instance": "/apps",
  "timestamp": "2024-01-20T10:30:00.000Z",
  "context": {
    "resource": "App",
    "identifier": "client_abc123"
  }
}

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

Retryable Errors
Non-Retryable Errors

// Errors that can be retried
const RETRYABLE_CODES = [
  'PROVIDER_INITIALIZATION_FAILED',
  'PROVIDER_ERROR',
  'PROVIDER_UNAVAILABLE',
  'PROVIDER_UNEXPECTED_RESPONSE',
  'SYSTEM_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.title)) {
        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));
    }
  }
}

// Errors that should NOT be retried
const NON_RETRYABLE_CODES = [
  'AUTH_INVALID_CREDENTIALS',
  'AUTH_INVALID_CLIENT',
  'AUTH_FORBIDDEN',
  'VALIDATION_MISSING_PARAMETER',
  'VALIDATION_INVALID_PARAMETER',
  'SESSION_INVALID_STATUS_TRANSITION',
  'PROVIDER_NOT_ENABLED',
  'RESOURCE_NOT_FOUND',
  'RESOURCE_CONFLICT',
  'IDEMPOTENCY_KEY_CONFLICT',
  'IDEMPOTENCY_REQUEST_IN_PROGRESS',
];

// Handle immediately without retry
function handleError(error) {
  if (NON_RETRYABLE_CODES.includes(error.title)) {
    // Log and return error to user
    console.error('Non-retryable error:', error);
    return { success: false, error };
  }
}

User Communication

Error Code	User-Friendly Message
`AUTH_INVALID_CREDENTIALS`	”Authentication failed. Please check your credentials.”
`VALIDATION_MISSING_PARAMETER`	”Some required information is missing. Please try again.”
`SESSION_NOT_FOUND`	”Your session has expired. Please start over.”
`SESSION_INVALID_STATUS_TRANSITION`	”This verification has already been completed.”
`PROVIDER_NOT_ENABLED`	”This identity provider is not available.”
`PROVIDER_UNAVAILABLE`	”The identity service is temporarily unavailable. Please try again later.”
`SYSTEM_INTERNAL_ERROR`	”Something went wrong on our end. Please try again.”
`RESOURCE_NOT_FOUND`	”The requested resource was not found.”
`IDEMPOTENCY_KEY_CONFLICT`	”Duplicate request detected with a different payload. Please retry with a new key.”
`IDEMPOTENCY_REQUEST_IN_PROGRESS`	”A matching request is still processing. Please try again shortly.”

Error Context

Always include relevant context when logging errors:

function logError(error, appContext) {
  console.error({
    // Error details from response
    title: error.title,
    status: error.status,
    detail: error.detail,
    instance: error.instance,
    timestamp: error.timestamp,
    context: error.context,
    // Application context
    verificationId: appContext.verificationId,
    userId: appContext.userId,
    provider: appContext.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

Overview

OIDC

REST API

Error Code Reference

Error Response Format

Response Fields

Error Code Structure

Authentication Errors

Validation Errors

Session Management Errors

Provider Errors

System Errors

Resource Errors

Error Categories

Error Handling Best Practices

Retry Strategy

User Communication

Error Context

Support

Developer Support

​Error Response Format

​Response Fields

​Error Code Structure

​Authentication Errors

​Validation Errors

​Session Management Errors

​Provider Errors

​System Errors

​Resource Errors

​Error Categories

​Error Handling Best Practices

​Retry Strategy

​User Communication

​Error Context

​Support

Developer Support

Error Response Format

Response Fields

Error Code Structure

Authentication Errors

Validation Errors

Session Management Errors

Provider Errors

System Errors

Resource Errors

Error Categories

Error Handling Best Practices

Retry Strategy

User Communication

Error Context

Support