Error Codes

Complete list of errors that AgeOnce API may return.

Error Format

All errors are returned in a standard format:

{
  "error": "error_code",
  "error_description": "Human readable description"
}

OAuth Errors

invalid_request

HTTP 400

Request contains invalid or missing parameters.

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

Causes:

Missing required parameter
Invalid parameter format
Duplicate parameters

Solution:

Check presence of all required parameters
Verify value formats

invalid_client

HTTP 401

Client authentication failed.

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

Causes:

Invalid client_id
Invalid client_secret
Client is deactivated

Solution:

Verify credentials
Ensure client is active in the Dashboard

invalid_grant

HTTP 400

Authorization code is invalid.

{
  "error": "invalid_grant",
  "error_description": "Authorization code has expired"
}

Causes:

Code was already used
Code expired (1 minute)
Code does not exist

Solution:

Use code immediately after receiving
Request new code via re-authorization

unauthorized_client

HTTP 403

Client is not authorized for this operation.

{
  "error": "unauthorized_client",
  "error_description": "Redirect URI does not match"
}

Causes:

redirect_uri not registered for the client
redirect_uri doesn't match the one used during authorization

Solution:

Register redirect_uri in the Dashboard
Use exactly the same URI

access_denied

HTTP 403

User declined verification.

{
  "error": "access_denied",
  "error_description": "User cancelled verification"
}

Causes:

User clicked "Cancel"
User closed the verification page

Solution:

Show user a message
Offer to try again

verification_failed

HTTP 403

Age verification failed.

{
  "error": "verification_failed",
  "error_description": "Age verification failed"
}

Causes:

User doesn't meet age requirements
Technical issue with verification

Solution:

Inform user of the result
Don't offer retry without reason

Token Errors

token_expired

During validation

{
  "valid": false,
  "error": "Token has expired"
}

Solution: Request new verification

invalid_signature

During validation

{
  "valid": false,
  "error": "Invalid signature"
}

Causes:

Token is forged
Token is corrupted
Invalid public key

Solution:

Verify you're using the correct JWKS
Refresh public key cache

invalid_issuer

During validation

{
  "valid": false,
  "error": "Invalid issuer"
}

Causes: Token is not from AgeOnce

Solution: Verify token source

HTTP Errors

500 Internal Server Error

{
  "error": "server_error",
  "error_description": "An unexpected error occurred"
}

Solution:

Try again later
Contact support if the error persists

Error Handling

Example (Node.js)

async function handleCallback(code) {
  try {
    const response = await fetch('/api/oauth/token', {
      method: 'POST',
      body: JSON.stringify({ code, /* ... */ }),
    });
    
    const data = await response.json();
    
    if (data.error) {
      switch (data.error) {
        case 'invalid_grant':
          // Code expired, need new verification
          return redirect('/verify');
          
        case 'invalid_client':
          // Configuration issue
          console.error('Check client credentials');
          return showError('Configuration error');
          
        case 'access_denied':
          // User cancelled
          return showMessage('Verification cancelled');
          
        default:
          return showError('Verification failed');
      }
    }
    
    return data.age_token;
    
  } catch (error) {
    console.error('Network error:', error);
    return showError('Connection failed');
  }
}

Always handle errors gracefully and show users clear messages.

Error Codes

On this page