Account Error Handling

Overview

Antigravity Manager automatically handles many account errors, but some require manual intervention. This page covers the most common account-related errors and their solutions.

Error Types

HTTP Status Codes

401 Unauthorized - Authentication failed, token expired or invalid
403 Forbidden - Account lacks required permissions or is blocked
429 Too Many Requests - Rate limit exceeded (auto-retries)
404 Not Found - Project or resource not found
503 Service Unavailable - Temporary service issues (auto-retries)

403 Forbidden Errors

403 errors indicate your account has been restricted or doesn’t have the required permissions.

Common Causes

Account requires verification
Geographic restrictions
Service terms violation
Temporary risk control (VALIDATION_REQUIRED)
Project permissions issue

Automatic Handling

When a 403 error occurs, Antigravity Manager automatically:

Marks the account as forbidden (is_forbidden: true)
Removes it from the active pool to prevent repeated failures
Attempts to switch to the next available account
Returns 503 instead of 403 to prevent client disconnection (for Claude Code)

From the source code (proxy/handlers/claude.rs:1277-1298):

if status_code == 403 {
    if error_text.contains("VALIDATION_REQUIRED") {
        // Temporarily block account for 10 minutes
        tracing::warn!("[Claude] VALIDATION_REQUIRED detected on account {}, temporarily blocking");
    }
    tracing::warn!("[Claude] Account {} marked as forbidden due to 403", email);
}

Solutions

Check for verification links

How to find:

Go to the Accounts page
Click on the disabled account
Look for error details containing “To continue, verify your account at…”
Click the verification link to complete Google’s verification process

What to expect:

Google may ask you to verify your phone number
You may need to complete a CAPTCHA
Some accounts may require additional identity verification

Confirm Google One AI Plan eligibility

Check your eligibility:

Visit the FAQ page
Ensure your account meets the requirements:
- Active Google One subscription (if required)
- Account in good standing
- Correct geographic region

For Gemini Code Assist:

Verify you have access to Vertex AI
Check project permissions in Google Cloud Console

Wait for automatic recovery

Temporary blocks:Some 403 errors are temporary (e.g., VALIDATION_REQUIRED):

The system automatically blocks the account for 10 minutes
After the block expires, the account is retried
If the issue persists, manual intervention is required

Risk control cooldown:

Google may temporarily restrict accounts that trigger automated abuse detection
These typically resolve within 24-48 hours
Reduce request frequency to avoid future blocks

Re-authorize the account

Steps:

Navigate to the Accounts page
Find the forbidden account (marked with 🚫)
Click “Delete” to remove the account
Add the account again:
- Click “Add Account” → “OAuth”
- Copy the authorization link
- Complete OAuth flow in your browser
- Wait for “Authorization successful” message

Re-authorization refreshes all tokens and can resolve stale permission issues.

Check account details for specific errors

View detailed error information:

Go to Accounts page
Click on the account card
Look for:
- disabled_reason: Why the account was disabled
- proxy_disabled_reason: Specific 403 reason
- validation_blocked: Temporary block status
- Detection timestamp

Common error messages:

"invalid_grant" - Refresh token revoked or expired
"VALIDATION_REQUIRED" - Google requires additional verification
"Forbidden (403): quota fetch denied" - No permission to access quotas

401 Unauthorized Errors

Common Causes

Expired access token (auto-refreshed)
Revoked refresh token (requires re-authorization)
Invalid OAuth credentials
Token not yet active

Automatic Handling

When a 401 error occurs:

Automatic token refresh is attempted first
If refresh fails, the account is marked as disabled
Account rotation to the next available account
Short retry delay (200ms) before switching

From the source code (modules/account.rs:1502-1524):

if code == 401 {
    tracing::warn!("401 Unauthorized for {}, forcing refresh...");
    // Attempt to refresh the token
    if let Err(e) = refresh_access_token(account_id) {
        if e.contains("invalid_grant") {
            // Disable account permanently
            account.disabled_reason = Some(format!("invalid_grant: {}", e));
        }
    }
}

Solutions

Wait for automatic refresh

When a 401 occurs:

Antigravity automatically attempts to refresh the access token
This happens in the background without user intervention
Most 401 errors are resolved within seconds

Monitor in Debug Console:

Settings → About → Debug Console
Look for “forcing refresh” messages
Check if refresh succeeds or fails

Handle invalid_grant errors

What is invalid_grant?This error means your refresh token has been:

Revoked by Google (security reasons)
Expired (typically after 6 months of inactivity)
Invalidated due to password change
Used in too many applications simultaneously

Solution:

invalid_grant errors cannot be automatically fixed. Manual re-authorization is required.

Remove the account:
- Go to Accounts page
- Delete the affected account
Re-authorize:
- Add the account again via OAuth
- Complete the authorization flow
- New refresh token will be issued

Prevention:

Don’t share Google accounts across multiple Antigravity instances
Don’t change your Google password frequently
Keep accounts actively used

Verify OAuth setup

Check OAuth configuration:

Ensure authorization link is current:
- When adding an account, always use the newly generated link
- Don’t reuse old authorization links
Complete OAuth flow:
- After clicking “Authorize”, you should see a browser callback
- Wait for “Authorization successful” message
- Don’t close the window prematurely

Verify tokens are saved:

# Check account files
ls ~/.antigravity_tools/accounts/

# View account JSON (check for access_token and refresh_token)
cat ~/.antigravity_tools/accounts/<account-id>.json

Token Expiry Issues

Understanding Token Lifecycle

Access Token: Valid for ~1 hour, automatically refreshed
Refresh Token: Valid for months, used to get new access tokens
Session Token: Temporary, for sticky sessions

Automatic Refresh Mechanism

Antigravity Manager automatically refreshes access tokens before they expire using the refresh token.

Refresh intervals:

Background refresh: Every 5 minutes (configurable)
On-demand refresh: When 401 is encountered
Pre-emptive refresh: 5 minutes before expiry

Manual Token Management

Force token refresh

Refresh a single account:

Go to Accounts page
Click on the account card
Click the refresh icon
Wait for quota to update

Refresh all accounts:

Go to Accounts page
Click “Refresh All” button
Monitor progress in the notification

Via API (for Docker/Headless):

curl -X POST http://localhost:8045/api/accounts/refresh-all \
  -H "Authorization: Bearer <your-api-key>"

Check token expiry times

View token details:

# Read account file
cat ~/.antigravity_tools/accounts/<account-id>.json | jq '.expires_at'

In the UI:

Click on an account card
Look for “Last synced” timestamp
This indicates when tokens were last refreshed

Handle expired refresh tokens

Symptoms:

Account keeps getting disabled
invalid_grant error in logs
Cannot refresh access token

Solution:

Expired refresh tokens require complete re-authorization.

Delete the account

Clear any cached credentials:

# Remove account file
rm ~/.antigravity_tools/accounts/<account-id>.json

Add the account fresh via OAuth

404 Project Not Found

This error usually indicates a Google Cloud project configuration issue.

Common Causes

Invalid project ID
Project deleted or moved
Insufficient permissions to access project
Project not enabled for Vertex AI

Solutions

Verify project exists

Check in Google Cloud Console:

Visit Google Cloud Console
Check the project selector
Search for the project ID mentioned in the error
If not found, the project may have been deleted

Create new project if needed:

Click “Create Project” in Google Cloud Console
Enable required APIs:
- Vertex AI API
- Gemini API
Wait for API enablement to complete

Fix empty or invalid project ID

From the source code (modules/account.rs:1580-1592):Antigravity automatically handles empty project IDs by:

Detecting when project_id is empty
Falling back to a stable default: bamboo-precept-lgxtn
Re-fetching quota with the fallback project

Manual fix:

Go to Accounts page
Delete account with invalid project
Re-add the account
System will auto-detect or use stable fallback

Enable Vertex AI API

Enable required APIs:

# Using gcloud CLI
gcloud services enable aiplatform.googleapis.com
gcloud services enable generativelanguage.googleapis.com

Or via Console:

Go to API Library
Search for “Vertex AI API”
Click “Enable”
Repeat for “Gemini API”

Account Management Best Practices

Preventing Issues

Don’t share accounts across instances:
- Using the same Google account in multiple Antigravity instances can cause token conflicts
- Each instance should have dedicated accounts
Monitor account health:
- Regularly check the Dashboard for quota status
- Set up background auto-refresh (Settings → Background Tasks)
- Enable quota protection to prevent overuse
Respond to errors promptly:
- Check disabled accounts daily
- Re-authorize accounts when invalid_grant occurs
- Complete verification prompts immediately
Use proxy pools for sensitive accounts:
- Assign specific proxies to accounts
- Rotate IPs to avoid rate limits
- See Settings → Proxy Pool

Monitoring Account Status

Account states:

✅ Active: Working normally
⏸️ Disabled: Manually disabled by user
🚫 Forbidden: Blocked due to 403 error
⚠️ Validation Blocked: Temporary block (10 minutes)
🔄 Syncing: Refreshing quota

Check account status:

# View account index
cat ~/.antigravity_tools/accounts/index.json | jq .

# Check for disabled accounts
cat ~/.antigravity_tools/accounts/index.json | jq '.[] | select(.disabled == true)'

Debugging Account Errors

For advanced debugging techniques, see the Debugging Guide.

Quick Debugging Steps

Check logs for error details:

tail -f ~/.antigravity_tools/logs/app.log | grep -i "error\|403\|401"

Enable debug console:
- Settings → About → Debug Console
- Monitor real-time request/response logs

Verify account file integrity:

# Check if account JSON is valid
cat ~/.antigravity_tools/accounts/<account-id>.json | jq .

Test OAuth flow manually:
- Add a test account
- Watch the browser callback
- Check for any errors in browser console

Common Issues - General troubleshooting
Debugging Guide - Advanced debugging techniques
API Documentation - Understanding API errors

Getting Started

Core Features

Integration Guides

Configuration

Deployment

Troubleshooting

Overview

Error Types

HTTP Status Codes

403 Forbidden Errors

Common Causes

Automatic Handling

Solutions

401 Unauthorized Errors

Common Causes

Automatic Handling

Solutions

Token Expiry Issues

Understanding Token Lifecycle

Automatic Refresh Mechanism

Manual Token Management

404 Project Not Found

Common Causes

Solutions

Account Management Best Practices

Preventing Issues

Monitoring Account Status

Debugging Account Errors

Quick Debugging Steps

Build docs developers (and LLMs) love

Getting Started

Core Features

Integration Guides

Configuration

Deployment

Troubleshooting

Documentation Index

​Overview

​Error Types

​HTTP Status Codes

​403 Forbidden Errors

​Common Causes

​Automatic Handling

​Solutions

​401 Unauthorized Errors

​Common Causes

​Automatic Handling

​Solutions

​Token Expiry Issues

​Understanding Token Lifecycle

​Automatic Refresh Mechanism

​Manual Token Management

​404 Project Not Found

​Common Causes

​Solutions

​Account Management Best Practices

​Preventing Issues

​Monitoring Account Status

​Debugging Account Errors

​Quick Debugging Steps

​Related Resources

Build docs developers (and LLMs) love

Overview

Error Types

HTTP Status Codes

403 Forbidden Errors

Common Causes

Automatic Handling

Solutions

401 Unauthorized Errors

Common Causes

Automatic Handling

Solutions

Token Expiry Issues

Understanding Token Lifecycle

Automatic Refresh Mechanism

Manual Token Management

404 Project Not Found

Common Causes

Solutions

Account Management Best Practices

Preventing Issues

Monitoring Account Status

Debugging Account Errors

Quick Debugging Steps

Related Resources