Error Code Catalog

This catalog documents all error messages returned by Hello World Co-Op DAO canisters, organized by service.

auth-service

Authentication Errors

Error Message	Cause	Resolution
Too many failed login attempts. Please try again in 10 minutes	Rate limiting triggered	Wait 10 minutes before retrying
Access token expired	JWT access token has expired	Use refresh token to get new access token
Refresh token expired	JWT refresh token has expired	User must re-authenticate
Invalid refresh token - possible reuse attack	Refresh token reused (security)	Re-authenticate from scratch
Device fingerprint mismatch - possible session hijacking	Device changed mid-session	Re-authenticate from the new device

Password Errors

Error Message	Cause	Resolution
Password must contain at least one number	Missing numeric character	Add at least one digit (0-9)
Password must contain at least one uppercase letter	Missing uppercase	Add at least one uppercase letter (A-Z)
Password must contain at least one lowercase letter	Missing lowercase	Add at least one lowercase letter (a-z)

Password Reset Errors

Error Message	Cause	Resolution
Too many password reset requests. Please try again in 1 hour.	Rate limiting	Wait 1 hour before requesting again
Reset token has expired. Please request a new password reset.	Token older than 24 hours	Request new password reset
Reset token has already been used. Please request a new password reset.	One-time token reused	Request new password reset

Configuration Errors

Error Message	Cause	Resolution
Unauthorized: Only controllers can set user service	Non-controller caller	Use controller identity
Unauthorized: Only controllers can set oracle bridge configuration	Non-controller caller	Use controller identity
Unauthorized: Only controllers can set frontend URL configuration	Non-controller caller	Use controller identity
Oracle bridge not configured. Call set_oracle_bridge() first.	Missing configuration	Controller must configure oracle bridge
Frontend URL not configured. Call set_frontend_url() first.	Missing configuration	Controller must configure frontend URL

user-service

Account Errors

Error Message	Cause	Resolution
Current password is incorrect	Wrong password on change	Verify current password
Email/password authentication not configured	No password credential	Use different auth method or set password
Session expired	Session no longer valid	Re-authenticate
Attestation has expired	OIDC attestation too old	Re-authenticate with provider

Password Errors

Error Message	Cause	Resolution
Password must contain at least one number	Missing numeric character	Add at least one digit (0-9)
Password must contain at least one uppercase letter	Missing uppercase	Add at least one uppercase letter (A-Z)
Password must contain at least one lowercase letter	Missing lowercase	Add at least one lowercase letter (a-z)
Password must contain at least one special character	Missing special char	Add special character (!@#$%^&*)

Linking Errors

Error Message	Cause	Resolution
This Internet Identity is already linked to another account	II anchor in use	Use different II or unlink from other account
This provider account is already linked to another user	OAuth account in use	Use different OAuth account
Session not found or expired	Invalid session token	Re-authenticate
Session does not belong to this user	Session/user mismatch	Re-authenticate as correct user

membership

Membership Errors

Error Message	Cause	Resolution
Principal already has a membership	Duplicate minting attempt	Check existing membership first
Renewal window is closed. Renewals are only allowed December 1 - January 31	Outside renewal period	Wait for renewal window
Payment proof is required for renewal	Missing attestation	Complete payment first
Revoked membership cannot be renewed - must apply as new member	Membership was revoked	Apply for new membership

Controller Errors

Error Message	Cause	Resolution
Controllers already initialized. Use set_controllers to modify.	Init called twice	Use set_controllers instead
Cannot set empty controllers list - this would lock the canister	Removing all controllers	Keep at least one controller
Cannot remove the last controller - this would lock the canister	Removing final controller	Add new controller first
Principal is not a controller	Non-controller in list	Verify principal ID
Auth service not configured	Missing auth-service principal	Controller must configure

governance

Proposal Errors

Error Message	Cause	Resolution
Title cannot be empty	Empty proposal title	Provide a title
Title too long (max 200 characters)	Title exceeds limit	Shorten title to 200 chars
Description cannot be empty	Empty proposal description	Provide a description
Proposal not approved	Trying to execute unapproved	Wait for approval vote
Proposal already executed	Duplicate execution attempt	Proposal can only execute once

Voting Errors

Error Message	Cause	Resolution
Already voted on this proposal	Duplicate vote attempt	Each member can vote once
Voting has not started yet	Before voting window	Wait for voting to begin
Voting period has ended	After voting window	Cannot vote after deadline
Proposal is not in active voting status	Wrong proposal state	Check proposal status
Not an active member	Caller not a member	Complete membership signup
Membership verification failed	Inter-canister call failed	Check membership canister

Configuration Errors

Error Message	Cause	Resolution
Unauthorized: controller access required	Non-controller caller	Use controller identity
Invalid percentage: must be 0-100	Invalid threshold value	Use value between 0-100

dom-token

Authorization Errors

Error Message	Cause	Resolution
Only admin can enable burn policies	Non-admin caller	Use admin identity
Only admin can disable burn policies	Non-admin caller	Use admin identity
Unauthorized: Only admin/controller can mint tokens	Non-admin caller	Use admin identity
Unauthorized: Only admin/controller can batch distribute tokens	Non-admin caller	Use admin identity

Transfer Errors (ICRC-1)

Error Message	Cause	Resolution
InsufficientFunds	Balance too low	Check balance before transfer
BadFee	Incorrect fee specified	Use icrc1_fee() to get correct fee
BadBurn	Burn amount below minimum	Increase burn amount
TooOld	Transaction timestamp too old	Use current timestamp
Duplicate	Transaction already processed	Check transaction ID

treasury

Configuration Errors

Error Message	Cause	Resolution
Auth service not configured	Missing auth-service principal	Controller must configure
Invalid session	Session token invalid	Re-authenticate

identity-gateway

Delegation Errors

Error Message	Cause	Resolution
Invalid delegation chain format: missing challenge	Malformed delegation	Re-authenticate with II
Invalid delegation chain format: missing principal	Malformed delegation	Re-authenticate with II
Invalid delegation chain: empty	No delegation provided	Include delegation in request
Invalid delegation chain: malformed format	Parse error	Check delegation format
Challenge not found or already used (replay attack prevented)	Challenge reused	Start new login flow
Challenge expired (must authenticate within 5 minutes)	Timeout	Complete auth within 5 min

Linking Errors

Error Message	Cause	Resolution
This Internet Identity is already linked to another account	II anchor in use	Use different II anchor
Unlinking Internet Identity requires email/password authentication. Please login with email/password first.	Wrong auth method	Login with email/password first

Device Errors

Error Message	Cause	Resolution
Device has been revoked	Device no longer authorized	Re-register device or use another

Self-Custody Errors

Error Message	Cause	Resolution
Custodial wallets not supported for governance. Please use self-custodial authentication (passkey/WebAuthn).	Using custodial wallet	Use passkey/WebAuthn authentication

Configuration Errors

Error Message	Cause	Resolution
Unauthorized: only controllers can configure auth service	Non-controller caller	Use controller identity
Unauthorized: only controllers can configure user service	Non-controller caller	Use controller identity

Common Patterns

Controller Authorization

Most configuration methods require controller access:

// Pattern used across canisters
if !is_controller(caller) {
    return Err("Unauthorized: Only controllers can...".to_string());
}

Resolution: Use dfx identity with a principal that is a canister controller.

Session Validation

Session-based methods validate tokens via auth-service:

Session expired
Session not found or expired
Invalid session

Resolution: Call refresh_tokens with valid refresh token, or re-authenticate.

Rate Limiting

Several operations have rate limits:

Operation	Limit	Window
Login attempts	5 failures	10 minutes
Password reset	3 requests	1 hour
Temp key requests	5-100	24 hours

Resolution: Wait for the cooldown period to expire.

Frontend Error Handling

When displaying errors to users, map technical errors to user-friendly messages:

const USER_FRIENDLY_ERRORS: Record<string, string> = {
  'Session expired': 'Your session has expired. Please log in again.',
  'Not an active member': 'You must be a member to perform this action.',
  'Already voted on this proposal': 'You have already voted on this proposal.',
  'Voting has not started yet': 'Voting for this proposal has not opened yet.',
  'Voting period has ended': 'The voting period for this proposal has closed.',
};

function getDisplayError(error: string): string {
  return USER_FRIENDLY_ERRORS[error] || 'An unexpected error occurred. Please try again.';
}