Firebase Rate Limit & Auth Errors: Fix 401, 403, 429, 502, 503 Fast

Understanding Firebase Rate Limit and Auth Errors

Firebase surfaces a cluster of related HTTP status codes that developers frequently conflate. Understanding exactly which layer is failing is the fastest path to a fix.

Step 1: Confirm Which Error You Actually Have

The Firebase JavaScript SDK surfaces errors through the error.code property. Server-side SDKs use gRPC status codes. Always log both:

// Client SDK — Firestore example
try {
  await db.collection('items').doc('abc').set(data);
} catch (err) {
  console.error('code:', err.code);       // e.g. "resource-exhausted"
  console.error('message:', err.message); // e.g. "Quota exceeded."
}

Firestore maps gRPC codes to these string codes:

• resource-exhausted → rate limit (429)
• permission-denied → 403 / Security Rules
• unauthenticated → 401 / missing or expired token
• unavailable → 503 / transient Firebase outage
• deadline-exceeded → timeout

Step 2: Diagnose Authentication Errors (401 / firebase token expired / firebase invalid token)

The most common cause is an expired ID token. Firebase ID tokens expire after 1 hour. The SDK auto-refreshes them in the background, but this fails in service workers, background tabs, or server environments.

Check token expiry on the client:

const user = firebase.auth().currentUser;
if (!user) {
  console.log('No authenticated user — redirect to login');
} else {
  // Force-refresh the token
  const token = await user.getIdToken(/* forceRefresh */ true);
  console.log('Fresh token obtained:', token.substring(0, 20) + '...');
  
  // Decode without verification to inspect claims
  const payload = JSON.parse(atob(token.split('.')[1]));
  console.log('Expires at:', new Date(payload.exp * 1000));
  console.log('Issued at:', new Date(payload.iat * 1000));
}

Server-side: verify token with Admin SDK:

const admin = require('firebase-admin');
try {
  const decoded = await admin.auth().verifyIdToken(idToken);
  console.log('UID:', decoded.uid);
} catch (err) {
  if (err.code === 'auth/id-token-expired') {
    // Client must call getIdToken(true) and retry
    return res.status(401).json({ error: 'TOKEN_EXPIRED' });
  }
  if (err.code === 'auth/argument-error') {
    // Malformed token — client bug or tampering
    return res.status(401).json({ error: 'INVALID_TOKEN' });
  }
}

Step 3: Diagnose Authorization Errors (403 / firebase unauthorized)

A 403 means the token is valid but Firestore Security Rules deny the operation. This is extremely common after deploying rules changes.

Quick Security Rules test in the Firebase Console:

1. Open Firebase Console → Firestore → Rules → Rules Playground
2. Set Auth State to authenticated with your test UID
3. Simulate the exact read/write operation that is failing

Common broken rule patterns:

// BAD — accidentally denies all authenticated users
rules_version = '2';
service cloud.firestore {
  match /databases/{database}/documents {
    match /users/{userId} {
      allow read, write: if request.auth.uid = userId; // = should be ==
    }
  }
}

// GOOD — correct equality check
rules_version = '2';
service cloud.firestore {
  match /databases/{database}/documents {
    match /users/{userId} {
      allow read, write: if request.auth != null
                         && request.auth.uid == userId;
    }
  }
}

Step 4: Diagnose Rate Limiting (firebase rate limited / firebase rate limit)

Firestore rate limits are per-document: 1 write per second sustained, with short bursts allowed. The Realtime Database has a 100 simultaneous connection limit on the Spark (free) plan.

Find which documents are hot:

# Use gcloud to check Firestore operation counts
gcloud firestore operations list --project=YOUR_PROJECT_ID

# Check current quotas in GCP Console
gcloud services quota list --service=firestore.googleapis.com --project=YOUR_PROJECT_ID

Implement exponential backoff (the definitive fix):

async function writeWithRetry(docRef, data, maxRetries = 5) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      await docRef.set(data);
      return; // success
    } catch (err) {
      if (err.code !== 'resource-exhausted' || attempt === maxRetries - 1) {
        throw err; // not a rate limit error, or out of retries
      }
      const backoffMs = Math.min(1000 * Math.pow(2, attempt), 30000);
      const jitter = Math.random() * 1000;
      console.warn(`Rate limited. Retrying in ${backoffMs + jitter}ms (attempt ${attempt + 1})`);
      await new Promise(resolve => setTimeout(resolve, backoffMs + jitter));
    }
  }
}

Batch writes to reduce document contention:

// Instead of 500 individual writes, use a batch
const batch = db.batch();
for (const item of items) {
  const ref = db.collection('items').doc(item.id);
  batch.set(ref, item);
}
await batch.commit(); // counts as fewer quota operations

Step 5: Diagnose Infrastructure Errors (firebase 502 / firebase 503)

502 and 503 errors originate from Firebase's servers. Check the status dashboard first before spending time debugging your code:

1. https://status.firebase.google.com — real-time Firebase status
2. https://status.cloud.google.com — underlying GCP infrastructure

If there is no active incident, a 503 can also indicate you've hit a project-level quota that requires a GCP quota increase request.

Step 6: Fix firebase connection refused and firebase timeout

In development — Emulator Suite not running:

# Start the emulator suite
firebase emulators:start --only firestore,auth

# Verify emulators are listening
curl http://localhost:8080  # Firestore emulator UI
curl http://localhost:9099  # Auth emulator

Ensure your app points to the emulator:

if (location.hostname === 'localhost') {
  db.useEmulator('localhost', 8080);
  firebase.auth().useEmulator('http://localhost:9099');
}

Firestore timeout on large queries:

// Add query limits and indexes to prevent timeout
const snapshot = await db.collection('logs')
  .where('userId', '==', uid)
  .orderBy('createdAt', 'desc')
  .limit(50) // Always limit large collections
  .get();

If you see The query requires an index, follow the link in the error message to create the composite index in the Firebase Console.

Step 7: Fix firebase authentication failed in Server SDKs

Server SDKs (Node.js, Python, Go, Java) authenticate using a service account JSON key file or Application Default Credentials (ADC).

# Verify ADC is configured correctly
gcloud auth application-default print-access-token

# Or set explicit service account path
export GOOGLE_APPLICATION_CREDENTIALS="/path/to/serviceAccountKey.json"

# Validate the service account has required roles
gcloud projects get-iam-policy YOUR_PROJECT_ID \
  --flatten='bindings[].members' \
  --filter='bindings.members:serviceAccount:YOUR_SA_EMAIL'

Required IAM roles for Firebase Admin SDK:

• roles/firebase.admin — full Firebase access
• roles/datastore.user — Firestore read/write only
• roles/firebaseauth.admin — Auth management only