Firebase Rate Limit, 401, 403, 502, 503 & Token Errors: Complete Troubleshooting Guide

Understanding Firebase Auth & API Errors

Firebase surfaces errors through two layers: the client SDK (which maps HTTP status codes to named error codes like auth/id-token-expired) and the REST/gRPC APIs underneath (which return raw 4xx/5xx HTTP codes). Understanding which layer generated the error is the first diagnostic step.

Error Code Taxonomy

Step 1: Identify Which Service Is Failing

Firebase is a suite of products. The error source matters because the fix differs:

• Firebase Authentication — sign-in, token issuance, user management
• Firestore — document reads/writes, real-time listeners
• Firebase Storage — file uploads/downloads
• Firebase Functions — HTTP callable and background triggers
• Firebase Hosting — static asset delivery and rewrites

Diagnostic command — check raw HTTP response:

curl -s -o /dev/null -w "%{http_code}" \
  -H "Authorization: Bearer $(gcloud auth print-identity-token)" \
  "https://firestore.googleapis.com/v1/projects/YOUR_PROJECT_ID/databases/(default)/documents/your-collection"

If you get 401, your token is invalid or expired. 403 means the token is valid but the Security Rules deny access. 429 means quota exhaustion.

Step 2: Diagnose 401 UNAUTHENTICATED

The most common cause is an expired ID token. Firebase ID tokens expire after 3600 seconds (1 hour). Long-running processes, server-side rendering apps, and service workers are frequent victims.

How to confirm token expiry:

# Decode the JWT payload (no library needed)
TOKEN="your.id.token.here"
payload=$(echo $TOKEN | cut -d'.' -f2 | base64 -d 2>/dev/null || echo $TOKEN | cut -d'.' -f2 | base64 --decode 2>/dev/null)
echo $payload | python3 -m json.tool | grep -E '"exp"|"iat"|"aud"'

Compare the exp field (Unix timestamp) against date +%s. If exp < now, the token is expired.

Fix for client SDK (JavaScript):

// Force token refresh before any authenticated request
const user = auth.currentUser;
if (user) {
  const token = await user.getIdToken(/* forceRefresh */ true);
  // Use `token` in your Authorization header
}

Fix for Admin SDK (Node.js server):

Never use user ID tokens on the server. Use a service account:

export GOOGLE_APPLICATION_CREDENTIALS="/path/to/serviceAccountKey.json"

Then initialize with:

import { initializeApp, cert } from 'firebase-admin/app';
const app = initializeApp({ credential: cert('/path/to/serviceAccountKey.json') });

Other 401 causes:

• Wrong project ID in client config (firebaseConfig.projectId)
• Revoked service account key — check GCP IAM Console → Service Accounts → Keys
• Missing Authorization: Bearer header in manual REST calls
• GOOGLE_APPLICATION_CREDENTIALS env var pointing to a deleted or wrong file

Step 3: Diagnose 403 PERMISSION_DENIED

A 403 means Firebase received your token, validated it, but Security Rules rejected the operation.

Check Security Rules in Firebase Console:

Navigate to Firestore Database → Rules. A common misconfiguration:

// WRONG: Default denies everything after the 30-day trial
rules_version = '2';
service cloud.firestore {
  match /databases/{database}/documents {
    match /{document=**} {
      allow read, write: if false; // <-- This blocks everything
    }
  }
}

Use the Rules Playground in Firebase Console to simulate the failing request with your exact UID and path.

403 from Authentication (unauthorized domain):

If your web app is served from a new domain and you see:

FirebaseError: Firebase: This domain is not authorized to run this operation.
(auth/unauthorized-domain)

Go to Firebase Console → Authentication → Settings → Authorized Domains and add your domain.

Step 4: Diagnose Firebase Rate Limit (429 / RESOURCE_EXHAUSTED)

Firebase has two distinct rate-limiting systems:

1. Firestore quotas (free Spark plan): 50,000 reads/day, 20,000 writes/day, 20,000 deletes/day
2. Authentication rate limits: 100 sign-ins per IP per minute (default)

Identify quota exhaustion in logs:

GRPC error 8: RESOURCE_EXHAUSTED: Quota exceeded for quota metric 'datastore.googleapis.com/api/request_count'

Check current quota usage:

gcloud firestore operations list --project=YOUR_PROJECT_ID
# Or via GCP Console: APIs & Services → Quotas → search "Firestore"

Implement exponential backoff (JavaScript):

async function firestoreWithRetry(operation, maxRetries = 5) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      return await operation();
    } catch (err) {
      if (err.code === 'resource-exhausted' || err.status === 429) {
        const delay = Math.min(1000 * Math.pow(2, attempt) + Math.random() * 500, 32000);
        console.warn(`Rate limited. Retrying in ${delay}ms (attempt ${attempt + 1})`);
        await new Promise(r => setTimeout(r, delay));
      } else {
        throw err; // Non-retryable error
      }
    }
  }
  throw new Error('Max retries exceeded');
}

Step 5: Diagnose 502 / 503 Errors

These are transient server-side errors from Google's infrastructure. They are not caused by your code.

Immediate checks:

1. Visit https://status.firebase.google.com — look for active incidents
2. Check https://status.cloud.google.com for underlying GCP issues
3. These errors typically self-resolve within minutes

If 503 persists beyond 10 minutes, check for:

• Firestore security rules with extremely complex queries causing server-side timeout
• Cloud Functions that exceed the 540-second timeout (returns 503 to the caller)
• Hosting rewrites pointing to a deleted Cloud Run service

Cloud Functions timeout fix:

gcloud functions deploy my-function \
  --timeout=540s \
  --memory=512MB \
  --project=YOUR_PROJECT_ID

Step 6: Diagnose Connection Refused

This error (ECONNREFUSED or connect ECONNREFUSED) is almost always a network or environment configuration issue, not a Firebase bug.

Common causes:

• Firebase emulator is not running but FIREBASE_EMULATOR_HOST env var is set
• Corporate firewall blocking outbound 443 to *.googleapis.com
• Docker container with no egress network configured

Test connectivity:

curl -v https://firestore.googleapis.com/
nslookup firestore.googleapis.com
traceroute firestore.googleapis.com

Check for accidental emulator config:

env | grep -i firebase
env | grep -i emulator
# Unset if wrong:
unset FIREBASE_EMULATOR_HOST
unset FIRESTORE_EMULATOR_HOST

Step 7: Monitoring & Prevention

Set up Cloud Monitoring alerts for quota usage:

gcloud alpha monitoring policies create \
  --notification-channels=YOUR_CHANNEL_ID \
  --display-name="Firestore quota warning" \
  --condition-display-name="Reads > 40000/day" \
  --condition-filter='metric.type="firestore.googleapis.com/document/read_count"' \
  --condition-threshold-value=40000 \
  --project=YOUR_PROJECT_ID

Enable Firebase Performance Monitoring in your app to catch latency spikes before they become 503s:

import { getPerformance } from 'firebase/performance';
const perf = getPerformance(app);