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": "Invalid or expired authorization code"
}

Expired codes return expired_code. A code that was already exchanged returns code_already_used. Both are HTTP 400.

Solution:

Exchange the code immediately. It expires after 60 seconds and can be used once
Start verification again if exchange fails

invalid_redirect_uri

HTTP 400

redirect_uri is not in the client's allow list, or it does not match the URI used when the code was created.

{
  "error": "invalid_redirect_uri",
  "error_description": "redirect_uri does not match"
}

Solution:

Register the exact redirect URI in the Dashboard
Send the same URI on token exchange, including scheme, host, port, and path

invalid_state

HTTP 400

The state on token exchange does not match the value stored with the authorization code.

age_requirement_not_met

HTTP 403

The verified age is below the age_required value for this check.

payment_required

HTTP 402

The client has reached its verification limit.

Token Errors

A failed check stays on the AgeOnce page. The API does not redirect back with error=access_denied.

Token validation (GET /api/verify/token/{access_token}) returns HTTP 401 when the token is invalid or expired:

{
  "success": false,
  "valid": false,
  "message": "Invalid or expired token"
}

Solution: Start verification again and exchange a new code. Local validation should use RS256, issuer https://ageonce.io, and the key from /api/.well-known/jwks.json or /api/verify/public-key.

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, state, redirectUri, credentials) {
  try {
    const response = await fetch('https://api.ageonce.com/api/oauth/token', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        Authorization: `Basic ${credentials}`,
      },
      body: JSON.stringify({
        grant_type: 'authorization_code',
        code,
        redirect_uri: redirectUri,
        state,
      }),
    });
    
    const data = await response.json();
    
    if (data.error) {
      switch (data.error) {
        case 'expired_code':
        case 'code_already_used':
          return redirect('/verify');
          
        case 'invalid_client':
          console.error('Check client credentials');
          return showError('Configuration error');
          
        case 'invalid_redirect_uri':
          return showError('Redirect URI is not registered');
          
        default:
          return showError('Verification failed');
      }
    }
    
    return data.access_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