firebase-admin

Postconditions — what we check

• verifyIdToken · token-expired

  error
  WhenID token has expired
  ThrowsFirebaseAuthError with code 'auth/id-token-expired'
  Required handlingCaller MUST catch and handle expired token errors. Return 401 Unauthorized to client and require re-authentication. DO NOT retry with same token - it's permanently expired.
  costhighin prodimmediate exceptionusers seelost datavisibilityvisible
  Sources[1]
• verifyIdToken · token-invalid

  error
  WhenID token is invalid (malformed, wrong project, revoked)
  ThrowsFirebaseAuthError with code 'auth/argument-error' or 'auth/id-token-revoked'
  Required handlingCaller MUST validate token format and handle invalid tokens. Check error.code to distinguish between format errors and revoked tokens. Return 401 Unauthorized to client.
  costhighin prodimmediate exceptionusers seelost datavisibilityvisible
  Sources[2]
• verifyIdToken · network-error

  error
  WhenNetwork request to Firebase Auth service failed
  ThrowsFirebaseAuthError or generic Error
  Required handlingCaller SHOULD implement retry with exponential backoff for transient failures. Check if Firebase Auth service is available.
  costhighin prodimmediate exceptionusers seelost datavisibilityvisible
  Sources[3]
• createUser · email-already-exists

  error
  WhenEmail address is already in use
  ThrowsFirebaseAuthError with code 'auth/email-already-exists'
  Required handlingCaller MUST check if error.code === 'auth/email-already-exists'. Return user-friendly error message. Consider suggesting password reset if user forgot they have an account. DO NOT retry with same email.
  costhighin prodimmediate exceptionusers seelost datavisibilityvisible
  Sources[1]
• createUser · invalid-email

  error
  WhenEmail format is invalid
  ThrowsFirebaseAuthError with code 'auth/invalid-email'
  Required handlingCaller SHOULD validate email format before calling createUser. Use email validation library to prevent this error.
  costhighin prodimmediate exceptionusers seelost datavisibilityvisible
  Sources[1]
• createUser · uid-already-exists

  error
  WhenProvided UID is already in use (when specifying custom UID)
  ThrowsFirebaseAuthError with code 'auth/uid-already-exists'
  Required handlingIf using custom UIDs, generate unique values. Catch this error and either generate new UID or handle collision.
  costhighin prodimmediate exceptionusers seelost datavisibilityvisible
  Sources[1]
• createUser · invalid-password

  error
  WhenPassword is too weak or doesn't meet requirements
  ThrowsFirebaseAuthError with code 'auth/invalid-password'
  Required handlingValidate password strength on client side. Firebase requires minimum 6 characters. Return helpful error to user about password requirements.
  costhighin prodimmediate exceptionusers seelost datavisibilityvisible
  Sources[4]
• getUser · user-not-found

  error
  WhenNo user record found for the given UID
  ThrowsFirebaseAuthError with code 'auth/user-not-found'
  Required handlingCaller MUST handle user-not-found errors. DO NOT assume user exists - always catch this error. Consider if this indicates deleted account or invalid UID.
  costhighin prodimmediate exceptionusers seelost datavisibilityvisible
  Sources[1]
• getUser · invalid-uid

  error
  WhenUID format is invalid
  ThrowsFirebaseAuthError with code 'auth/invalid-uid'
  Required handlingValidate UID format before calling getUser. Firebase UIDs are typically 28-character strings.
  costhighin prodimmediate exceptionusers seelost datavisibilityvisible
  Sources[1]
• updateUser · user-not-found

  error
  WhenNo user record found for the given UID
  ThrowsFirebaseAuthError with code 'auth/user-not-found'
  Required handlingCaller MUST handle user-not-found errors. Decide whether to create user or return error.
  costhighin prodimmediate exceptionusers seelost datavisibilityvisible
  Sources[1]
• updateUser · email-already-exists

  error
  WhenNew email address is already in use by another user
  ThrowsFirebaseAuthError with code 'auth/email-already-exists'
  Required handlingCheck if new email is available before updating. Return user-friendly error if email is taken.
  costhighin prodimmediate exceptionusers seelost datavisibilityvisible
  Sources[1]
• deleteUser · user-not-found

  error
  WhenNo user record found for the given UID
  ThrowsFirebaseAuthError with code 'auth/user-not-found'
  Required handlingCaller SHOULD handle user-not-found errors gracefully. Consider if idempotent delete is acceptable (user already deleted).
  costhighin prodimmediate exceptionusers seelost datavisibilityvisible
  Sources[1]
• getUserByEmail · user-not-found

  error
  WhenNo user record with the given email
  ThrowsFirebaseAuthError with code 'auth/user-not-found'
  Required handlingCaller MUST handle user-not-found errors. This is common when checking if email is registered.
  costhighin prodimmediate exceptionusers seelost datavisibilityvisible
  Sources[1]
• setCustomUserClaims · user-not-found

  error
  WhenNo user record found
  ThrowsFirebaseAuthError with code 'auth/user-not-found'
  Required handlingVerify user exists before setting claims.
  costhighin prodimmediate exceptionusers seelost datavisibilityvisible
  Sources[1]
• setCustomUserClaims · invalid-claims

  error
  WhenClaims object exceeds 1000 bytes or uses reserved keys
  ThrowsFirebaseAuthError with code 'auth/invalid-claims'
  Required handlingValidate claims size and avoid reserved keys. Reserved keys: iss, sub, aud, exp, iat, auth_time, nonce, etc.
  costhighin prodimmediate exceptionusers seelost datavisibilityvisible
  Sources[5]
• get · permission-denied

  error
  WhenSecurity rules deny read access
  ThrowsError with code 'PERMISSION_DENIED' (gRPC code 7)
  Required handlingCaller MUST handle permission errors. Check Firestore security rules. Admin SDK bypasses rules by default - if seeing this, check service account permissions.
  costhighin prodimmediate exceptionusers seelost datavisibilityvisible
  Sources[6]
• get · not-found

  error
  WhenDocument does not exist
  ReturnsDocumentSnapshot with exists: false
  Required handlingCaller MUST check snapshot.exists before accessing data. Use snapshot.exists or check if snapshot.data() is undefined.
  costhighin prodimmediate exceptionusers seelost datavisibilityvisible
  Sources[7]
• get · deadline-exceeded

  error
  WhenOperation timed out
  ThrowsError with code 'DEADLINE_EXCEEDED' (gRPC code 4)
  Required handlingCaller SHOULD implement retry with exponential backoff. Check network connectivity and Firestore status. Consider if query is too complex (missing indexes).
  costhighin prodimmediate exceptionusers seelost datavisibilityvisible
  Sources[6]
• add · permission-denied

  error
  WhenSecurity rules deny write access
  ThrowsError with code 'PERMISSION_DENIED' (gRPC code 7)
  Required handlingCheck Firestore security rules and service account permissions.
  costhighin prodimmediate exceptionusers seelost datavisibilityvisible
  Sources[6]
• add · resource-exhausted

  error
  WhenWrite quota exceeded or rate limit hit
  ThrowsError with code 'RESOURCE_EXHAUSTED' (gRPC code 8)
  Required handlingCaller MUST handle quota errors. Check if billing is enabled (free tier limits). Implement backoff and reduce write rate. Avoid writing to lexicographically close documents (hot spots).
  costhighin prodimmediate exceptionusers seelost datavisibilityvisible
  Sources[8]
• set · aborted

  error
  WhenTransaction aborted due to contention
  ThrowsError with code 'ABORTED' (gRPC code 10)
  Required handlingCaller SHOULD retry with exponential backoff and jitter. Occurs when multiple transactions access same data. Consider redesigning to reduce contention.
  costhighin prodimmediate exceptionusers seelost datavisibilityvisible
  Sources[6]
• set · resource-exhausted

  error
  WhenWrite quota exceeded
  ThrowsError with code 'RESOURCE_EXHAUSTED'
  Required handlingImplement rate limiting and backoff. Check daily write quota and billing status.
  costhighin prodimmediate exceptionusers seelost datavisibilityvisible
  Sources[8]
• update · not-found

  error
  WhenDocument to update does not exist
  ThrowsError with code 'NOT_FOUND' (gRPC code 5)
  Required handlingCaller MUST handle not-found errors. Use set() with merge: true if you want to create-or-update. update() requires document to exist.
  costhighin prodimmediate exceptionusers seelost datavisibilityvisible
  Sources[9]
• update · aborted

  error
  WhenTransaction contention
  ThrowsError with code 'ABORTED'
  Required handlingRetry with exponential backoff.
  costhighin prodimmediate exceptionusers seelost datavisibilityvisible
  Sources[6]
• delete · permission-denied

  error
  WhenSecurity rules deny delete access
  ThrowsError with code 'PERMISSION_DENIED'
  Required handlingCheck security rules and permissions.
  costhighin prodimmediate exceptionusers seelost datavisibilityvisible
  Sources[6]
• send · invalid-recipient

  error
  WhenDevice token is invalid, expired, or unregistered
  ThrowsFirebaseMessagingError with code 'messaging/invalid-recipient'
  Required handlingCaller MUST remove invalid tokens from database. Check error code and error.code === 'messaging/invalid-recipient'. Tokens can expire if user uninstalls app or revokes permissions.
  costhighin prodimmediate exceptionusers seelost datavisibilityvisible
  Sources[10]
• send · invalid-argument

  error
  WhenMessage payload is malformed or exceeds size limits
  ThrowsFirebaseMessagingError with code 'messaging/invalid-argument'
  Required handlingValidate message structure before sending. Check payload size limits (4KB for data messages). Verify required fields are present.
  costhighin prodimmediate exceptionusers seelost datavisibilityvisible
  Sources[10]
• send · quota-exceeded

  error
  WhenFCM rate limit exceeded
  ThrowsFirebaseMessagingError with code 'messaging/quota-exceeded'
  Required handlingImplement exponential backoff retry. Reduce message send rate. Check if quota limit is reasonable for use case.
  costhighin prodimmediate exceptionusers seelost datavisibilityvisible
  Sources[10]
• sendMulticast · partial-failure

  error
  WhenSome tokens succeeded, some failed
  ReturnsBatchResponse with failureCount > 0
  Required handlingCaller MUST check response.failureCount and response.responses array. Each response contains success boolean and optional error. Remove invalid tokens from database based on specific error codes.
  costhighin prodimmediate exceptionusers seelost datavisibilityvisible
  Sources[11]
• sendMulticast · invalid-argument

  error
  WhenInvalid tokens or payload
  ThrowsFirebaseMessagingError
  Required handlingValidate all tokens and payload before sending.
  costhighin prodimmediate exceptionusers seelost datavisibilityvisible
  Sources[10]
• sendToTopic · invalid-topic

  error
  WhenTopic name is invalid or doesn't exist
  ThrowsFirebaseMessagingError with code 'messaging/invalid-argument'
  Required handlingValidate topic name format. Topic names must match /topics/[a-zA-Z0-9-_.~%]+
  costhighin prodimmediate exceptionusers seelost datavisibilityvisible
  Sources[12]
• once · permission-denied

  error
  WhenDatabase rules deny read access
  ThrowsError with code 'PERMISSION_DENIED'
  Required handlingCheck Realtime Database rules. Admin SDK bypasses rules by default - if seeing this, check databaseAuthVariableOverride.
  costhighin prodimmediate exceptionusers seelost datavisibilityvisible
  Sources[13]
• once · network-error

  error
  WhenNetwork connection failed
  ThrowsError
  Required handlingImplement retry with exponential backoff for transient failures.
  costhighin prodimmediate exceptionusers seelost datavisibilityvisible
  Sources[3]
• set · permission-denied

  error
  WhenDatabase rules deny write access
  ThrowsError with code 'PERMISSION_DENIED'
  Required handlingCheck database rules and authentication.
  costhighin prodimmediate exceptionusers seelost datavisibilityvisible
  Sources[14]
• update · permission-denied

  error
  WhenDatabase rules deny write access
  ThrowsError with code 'PERMISSION_DENIED'
  Required handlingCheck database rules.
  costhighin prodimmediate exceptionusers seelost datavisibilityvisible
  Sources[14]
• remove · permission-denied

  error
  WhenDatabase rules deny delete access
  ThrowsError with code 'PERMISSION_DENIED'
  Required handlingCheck database rules.
  costhighin prodimmediate exceptionusers seelost datavisibilityvisible
  Sources[14]
• createSessionCookie · session-cookie-invalid-duration

  error
  WhenexpiresIn is not provided, not a number, or outside the allowed range (5 minutes to 2 weeks)
  ThrowsFirebaseAuthError with code 'auth/invalid-session-cookie-duration'
  Required handlingValidate expiresIn is a number between 300000ms (5 min) and 1209600000ms (2 weeks) before calling. Catch this error and return 400 Bad Request with a clear message. This error rejects synchronously — no network call is made.
  costhighin prodimmediate exceptionusers seeauthentication failurevisibilityvisible
  Sources[1]
• createSessionCookie · session-cookie-invalid-id-token

  error
  WhenID token is malformed, expired, or belongs to a different Firebase project
  ThrowsFirebaseAuthError with code 'auth/invalid-id-token'
  Required handlingCatch this error at the login endpoint and return 401 Unauthorized. The ID token must be recently issued (within 5 minutes). Require the front-end to obtain a fresh ID token and retry.
  costhighin prodimmediate exceptionusers seeauthentication failurevisibilityvisible
  Sources[1]
• createSessionCookie · session-cookie-network-error

  error
  WhenFirebase Auth service is unreachable
  ThrowsFirebaseAuthError or network Error
  Required handlingCatch network errors at the login endpoint and return 503 Service Unavailable. Implement exponential backoff retry for transient failures.
  costhighin prodimmediate exceptionusers seeauthentication failurevisibilityvisible
  Sources[1]
• verifySessionCookie · session-cookie-expired

  error
  WhenSession cookie's expiry time has passed
  ThrowsFirebaseAuthError with code 'auth/session-cookie-expired'
  Required handlingCatch in authentication middleware. Clear the session cookie and redirect to login. DO NOT retry — the cookie is permanently expired.
  costhighin prodimmediate exceptionusers seeauthentication failurevisibilityvisible
  Sources[1]
• verifySessionCookie · session-cookie-revoked

  error
  WhencheckRevoked=true and the user's session was revoked via revokeRefreshTokens()
  ThrowsFirebaseAuthError with code 'auth/session-cookie-revoked'
  Required handlingCatch in authentication middleware alongside cookie-expired. Clear the session cookie and redirect to login. Distinguish from expired for proper UX messaging.
  costhighin prodimmediate exceptionusers seeauthentication failurevisibilityvisible
  Sources[1]
• verifySessionCookie · session-cookie-invalid

  error
  WhenSession cookie is malformed, has invalid signature, or belongs to different Firebase project
  ThrowsFirebaseAuthError with code 'auth/argument-error' or similar
  Required handlingCatch in authentication middleware. Return 401 Unauthorized and clear the invalid cookie. Never swallow this error — tampered cookies must be rejected.
  costhighin prodimmediate exceptionusers seeauthentication failurevisibilityvisible
  Sources[1]
• verifySessionCookie · session-cookie-user-disabled

  error
  WhencheckRevoked=true and the user account has been disabled
  ThrowsFirebaseAuthError with code 'auth/user-disabled'
  Required handlingCatch separately from cookie-expired and cookie-revoked. Return a disabled-account response, not a generic 401. Requires network call to Firebase Auth.
  costmediumin prodimmediate exceptionusers seeauthentication failurevisibilityvisible
  Sources[1]
• createCustomToken · custom-token-invalid-uid

  error
  Whenuid is empty, not a string, or exceeds 128 characters
  ThrowsFirebaseAuthError with code 'auth/argument-error'
  Required handlingValidate uid is a non-empty string of 128 chars or fewer before calling. Catch and return 400 Bad Request. This rejects synchronously before signing.
  costmediumin prodimmediate exceptionusers seeauthentication failurevisibilityvisible
  Sources[15]
• createCustomToken · custom-token-invalid-claims

  error
  WhendeveloperClaims contains reserved JWT keys (iss, sub, aud, exp, iat, firebase, etc.)
  ThrowsFirebaseAuthError with code 'auth/argument-error'
  Required handlingAvoid reserved JWT claim keys in developerClaims. Validate claims object does not contain reserved names before calling. Catch and return 400.
  costmediumin prodimmediate exceptionusers seeauthentication failurevisibilityvisible
  Sources[15]
• createCustomToken · custom-token-signing-error

  error
  WhenService account private key is invalid, revoked, or corrupt
  ThrowsFirebaseAuthError with code 'auth/invalid-credential'
  Required handlingCatch and alert on this error — it indicates service account misconfiguration. Return 500 Internal Server Error. Do not retry. Requires manual key rotation fix.
  costhighin prodimmediate exceptionusers seeauthentication failurevisibilityvisible
  Sources[15]
• revokeRefreshTokens · revoke-tokens-user-not-found

  error
  WhenUID does not correspond to an existing Firebase user
  ThrowsFirebaseAuthError with code 'auth/user-not-found'
  Required handlingCatch and treat as success — user is already gone so revocation is moot. Log the discrepancy but do not crash the security incident handler.
  costlowin prodimmediate exceptionusers seedegraded performancevisibilityvisible
  Sources[1]
• revokeRefreshTokens · revoke-tokens-network-error

  error
  WhenFirebase Auth service is unreachable during revocation
  ThrowsFirebaseAuthError or network Error
  Required handlingMUST catch and retry on network failure. Failed revocation during a security incident leaves compromised sessions active. Implement exponential backoff. Alert if retries are exhausted.
  costhighin prodimmediate exceptionusers seedegraded performancevisibilitysilent
  Sources[1]
• generatePasswordResetLink · password-reset-user-not-found

  error
  WhenNo user exists with the specified email address
  ThrowsFirebaseAuthError with code 'auth/email-not-found' or 'auth/user-not-found'
  Required handlingCatch and return success regardless to prevent email enumeration attacks. Do not reveal whether the email is registered. Log the error internally.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1]
• generatePasswordResetLink · password-reset-invalid-email

  error
  WhenEmail format is invalid
  ThrowsFirebaseAuthError with code 'auth/invalid-email'
  Required handlingValidate email format with a regex or Zod schema before calling. Catch and return 400 Bad Request with a user-friendly message.
  costlowin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1]
• runTransaction · transaction-aborted-max-retries

  error
  WhenTransaction contention persists across all 5 automatic retry attempts
  ThrowsError with gRPC code ABORTED (code 10) — message: 'Too much contention on these datastore entities. Please try again.'
  Required handlingCatch the final rejection after retries are exhausted and return a 409 Conflict or retry the full operation at the application level with backoff. Do not swallow this error — silent swallowing causes lost writes that appear as stale data.
  costhighin prodimmediate exceptionusers seedegraded performancevisibilitysilent
  Sources[6]
• runTransaction · transaction-deadline-exceeded

  error
  WhenTransaction execution exceeds Firestore's 60-second server deadline
  ThrowsError with gRPC code DEADLINE_EXCEEDED (code 4)
  Required handlingCatch and treat as a non-retryable failure — the transaction was rolled back. For background jobs, return a failure result. For API routes, return 503. Break large transactions into smaller units to avoid hitting the deadline.
  costhighin prodimmediate exceptionusers seelost datavisibilitysilent
  Sources[6]
• runTransaction · transaction-failed-offline

  error
  WhenFirestore service is unreachable or the network connection is unavailable
  ThrowsError with gRPC code UNAVAILABLE (code 14)
  Required handlingCatch and implement external retry with exponential backoff. The Admin SDK does NOT queue offline — it fails immediately. Background jobs MUST retry externally when UNAVAILABLE errors occur during network partitions.
  costhighin prodimmediate exceptionusers seelost datavisibilitysilent
  Sources[6]
• runTransaction · transaction-function-side-effects

  warning
  WhenThe transaction update function contains side effects that execute on every retry attempt
  ThrowsNo throw — side effects execute silently N times (up to 5)
  Required handlingKeep the updateFunction free of observable side effects beyond Firestore writes. Move external API calls, payments, and email sends to AFTER the transaction resolves.
  costhighin prodsilent failureusers seelost transactionvisibilitysilent
  Sources[16]
• commit · batch-resource-exhausted

  error
  WhenWrite quota is exceeded or batch causes a hot-spot on a document
  ThrowsError with gRPC code RESOURCE_EXHAUSTED (code 8)
  Required handlingCatch and implement exponential backoff retry. Batch commits that hit RESOURCE_EXHAUSTED have NOT been applied — retry the full batch. Add jitter to backoff to prevent thundering herd in serverless deployments.
  costhighin prodimmediate exceptionusers seelost datavisibilitysilent
  Sources[6]
• commit · batch-aborted

  error
  WhenBatch write fails due to document contention
  ThrowsError with gRPC code ABORTED (code 10)
  Required handlingCatch ABORTED and retry the full batch from scratch. WriteBatch does NOT automatically retry unlike runTransaction(). No writes are applied on ABORTED — the batch is atomic and all-or-nothing.
  costhighin prodimmediate exceptionusers seelost datavisibilitysilent
  Sources[6]
• commit · batch-too-many-operations

  error
  WhenBatch contains more than 500 write operations
  ThrowsError with gRPC INVALID_ARGUMENT — Firestore's hard 500-operation limit per batch
  Required handlingSplit large datasets into chunks of 500 or fewer before committing. Validate batch size before calling commit(). The SDK throws before sending to the server — no partial writes occur.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[16]
• sendEach · send-each-partial-failure

  error
  WhenOne or more messages fail to send while others succeed (partial failure)
  ThrowsPromise resolves with BatchResponse where failureCount > 0; does NOT reject on partial failure
  Required handlingAfter every sendEach() call, check response.failureCount. If > 0, iterate response.responses to find per-message errors. Remove tokens with 'messaging/registration-token-not-registered' from the database. failureCount === messages.length means total failure with no deliveries.
  costmediumin prodsilent failureusers seedegraded performancevisibilitysilent
  Sources[11]
• sendEach · send-each-rate-exceeded

  error
  WhenGlobal FCM send rate limit is exceeded during batch send
  ThrowsFirebaseMessagingError with code 'messaging/message-rate-exceeded'
  Required handlingCatch and implement exponential backoff before retrying. This is a global rate limit (not per-device). Reduce send frequency or fan out over time. Distinguish from per-device 'messaging/device-message-rate-exceeded' errors that appear in per-message response.responses[i].error.
  costmediumin prodimmediate exceptionusers seedegraded performancevisibilitysilent
  Sources[10]
• sendEach · send-each-invalid-argument

  error
  WhenMessage payloads are malformed, tokens are empty strings, or required fields are missing
  ThrowsFirebaseMessagingError with code 'messaging/invalid-argument'
  Required handlingValidate all message objects before calling sendEach(). Ensure tokens are non-empty strings. Catch and return 400 Bad Request. Input validation before the call prevents the entire batch from being rejected.
  costmediumin prodimmediate exceptionusers seedegraded performancevisibilityvisible
  Sources[10]
• subscribeToTopic · subscribe-partial-failure

  error
  WhenOne or more tokens fail to subscribe while others succeed
  ThrowsPromise resolves with MessagingTopicManagementResponse where errors array is non-empty; does NOT reject
  Required handlingAfter every subscribeToTopic() call, check response.errors array. Remove tokens with 'messaging/registration-token-not-registered' from the database. Partial success means some tokens were subscribed; do not assume all succeeded when Promise resolves.
  costlowin prodsilent failureusers seedegraded performancevisibilitysilent
  Sources[17]
• subscribeToTopic · subscribe-invalid-topic

  error
  WhenTopic name is invalid — does not match /topics/[a-zA-Z0-9-_.~%]+ pattern
  ThrowsFirebaseMessagingError with code 'messaging/invalid-argument'
  Required handlingValidate topic names before calling. Topic names must match [a-zA-Z0-9-_.~%]+ (the /topics/ prefix is added automatically if omitted). Catch and return 400 Bad Request for invalid topic name inputs.
  costlowin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[17]
• importUsers · import-users-batch-too-large

  error
  Whenusers array contains more than 1000 records
  ThrowsFirebaseAuthError with code 'auth/maximum-user-count-exceeded'
  Required handlingSplit user arrays into chunks of 1000 before calling importUsers(). The SDK throws synchronously before any network call. Validate batch size before calling to avoid this failure mid-migration.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[18]
• importUsers · import-users-partial-failure

  error
  WhenOne or more individual user records fail validation or import while others succeed
  ThrowsPromise RESOLVES with UserImportResult where failureCount > 0; does NOT reject on per-user failure
  Required handlingAfter every importUsers() call, check result.failureCount. If > 0, inspect result.errors array — each entry contains index (original array position) and error (the failure reason). DO NOT assume all users were imported when the Promise resolves. Per-user failures include invalid email, duplicate UID, invalid password hash, and provider data conflicts. Log per-user errors for remediation.
  costhighin prodsilent failureusers seedegraded performancevisibilitysilent
  Sources[19]
• importUsers · import-users-tenant-mismatch

  error
  WhenUser records contain tenantId fields that don't match the TenantAwareAuth tenant context
  ThrowsFirebaseAuthError with code 'auth/mismatching-tenant-id'
  Required handlingWhen using multi-tenancy: ensure all user records in the batch have tenantId matching the TenantAwareAuth instance. Catch this error and reject the entire import batch — this is a configuration error.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[18]
• generateSignInWithEmailLink · sign-in-link-missing-action-code-settings

  error
  WhenactionCodeSettings parameter is missing, null, or undefined
  ThrowsFirebaseAuthError with code 'auth/argument-error' — 'actionCodeSettings is required'
  Required handlingAlways pass actionCodeSettings with at least url (the deep link the user is redirected to after clicking). This error is thrown synchronously — no network call occurs. Catch and return 400 Bad Request.
  costlowin prodimmediate exceptionusers seeauthentication failurevisibilityvisible
  Sources[18]
• generateSignInWithEmailLink · sign-in-link-user-not-found

  error
  WhenNo Firebase user exists with the given email address
  ThrowsFirebaseAuthError with code 'auth/email-not-found' or 'auth/user-not-found'
  Required handlingFor sign-in links, user-not-found may indicate the email is not registered. Catch and return success regardless to prevent email enumeration attacks. Do not reveal whether the email is registered.
  costlowin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1]
• generateSignInWithEmailLink · sign-in-link-network-error

  error
  WhenFirebase Auth service is unreachable
  ThrowsFirebaseAuthError or network Error
  Required handlingCatch and retry with exponential backoff for transient failures. Return 503 to the caller if retries are exhausted.
  costlowin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1]
• generateVerifyAndChangeEmailLink · verify-change-email-missing-new-email

  error
  WhennewEmail parameter is undefined, null, or missing
  ThrowsFirebaseAuthError with code 'auth/argument-error' — 'newEmail is required'
  Required handlingAlways pass newEmail as the second argument. This error is thrown synchronously — no network call occurs. Validate both email and newEmail before calling. Catch and return 400 Bad Request.
  costlowin prodimmediate exceptionusers seeauthentication failurevisibilityvisible
  Sources[18]
• generateVerifyAndChangeEmailLink · verify-change-email-invalid-email

  error
  WhenCurrent email or newEmail is not a valid email format
  ThrowsFirebaseAuthError with code 'auth/invalid-email'
  Required handlingValidate both email addresses with a regex or Zod schema before calling. Catch and return 400 Bad Request with a user-friendly message.
  costlowin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1]
• generateVerifyAndChangeEmailLink · verify-change-email-user-not-found

  error
  WhenNo user exists with the given current email address
  ThrowsFirebaseAuthError with code 'auth/email-not-found' or 'auth/user-not-found'
  Required handlingCatch and handle gracefully. Avoid revealing whether email is registered in publicly accessible endpoints (email enumeration prevention).
  costlowin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1]
• getTemplate · remote-config-get-permission-denied

  error
  WhenService account lacks Remote Config Viewer or Editor role
  ThrowsFirebaseRemoteConfigError with code 'remote-config/permission-denied'
  Required handlingCatch and alert — this is a service account misconfiguration that will prevent all Remote Config reads. Return 500 to the caller. Grant the Firebase Remote Config Admin role to the service account in IAM. Do not retry — this error is not transient.
  costhighin prodimmediate exceptionusers seeservice unavailablevisibilitysilent
  Sources[20]
• getTemplate · remote-config-get-quota-exceeded

  warning
  WhenRemote Config REST API quota is exceeded (default: 2000 requests/day for GET)
  ThrowsFirebaseRemoteConfigError with code 'remote-config/resource-exhausted'
  Required handlingCache the Remote Config template locally rather than fetching it on every request. Implement a TTL-based cache (Firebase recommends 15 minutes for most use cases). Catch this error and serve the last cached template. Do not fetch on every user request — this rapidly exhausts quota.
  costmediumin prodimmediate exceptionusers seedegraded performancevisibilitysilent
  Sources[21]
• getTemplate · remote-config-get-network-error

  error
  WhenFirebase Remote Config service is unreachable or network fails
  ThrowsFirebaseRemoteConfigError with code 'remote-config/unknown-error' or network Error
  Required handlingCatch and serve last cached template if available. Implement exponential backoff retry for transient failures. Do not crash the application when Remote Config is temporarily unavailable — serve defaults instead.
  costmediumin prodimmediate exceptionusers seedegraded performancevisibilitysilent
  Sources[20]
• publishTemplate · remote-config-publish-etag-mismatch

  error
  WhenTemplate ETag does not match the current server ETag — another process published the template after getTemplate() was called
  ThrowsFirebaseRemoteConfigError with code 'remote-config/aborted'
  Required handlingCatch 'remote-config/aborted' and retry: call getTemplate() to get the latest template, reapply your changes to it, then call publishTemplate() again. This prevents overwriting concurrent changes. Using force:true bypasses the ETag but risks losing changes made by other processes.
  costmediumin prodimmediate exceptionusers seelost datavisibilityvisible
  Sources[20]
• publishTemplate · remote-config-publish-invalid-template

  error
  WhenTemplate has missing ETag, invalid conditions, or malformed parameter values
  ThrowsFirebaseRemoteConfigError with code 'remote-config/invalid-argument'
  Required handlingCall validateTemplate() before publishTemplate() to catch structural errors without committing them. Catch 'invalid-argument' and log the error details — these indicate template schema violations.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[20]
• publishTemplate · remote-config-publish-quota-exceeded

  error
  WhenRemote Config write quota exceeded (default: 1 publish per second per project)
  ThrowsFirebaseRemoteConfigError with code 'remote-config/resource-exhausted'
  Required handlingImplement rate limiting before publishing — only one publish per second is allowed. Catch this error and retry after a 1-second delay. Do not use publishTemplate() in hot code paths — it is an admin operation.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[21]
• validateTemplate · remote-config-validate-invalid-argument

  error
  WhenTemplate has missing ETag, malformed conditions, invalid parameter names, or circular references
  ThrowsFirebaseRemoteConfigError with code 'remote-config/invalid-argument'
  Required handlingCatch and inspect the error message — the server returns specific details about what is invalid (e.g., invalid condition expression, reserved parameter name). Fix the template structure before retrying. This is the expected failure mode — validateTemplate() is specifically designed to surface these errors before they affect production.
  costlowin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[20]
• validateTemplate · remote-config-validate-permission-denied

  error
  WhenService account lacks Remote Config Editor or Admin role
  ThrowsFirebaseRemoteConfigError with code 'remote-config/permission-denied'
  Required handlingCatch and alert on this error — it indicates service account misconfiguration. The service account requires Firebase Remote Config Admin role, not just Viewer. Return 500 Internal Server Error. Do not retry.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[20]
• createProviderConfig · create-provider-config-invalid-provider-id

  error
  WhenproviderId does not start with 'saml.' or 'oidc.' prefix, or is missing from the config object entirely
  ThrowsFirebaseAuthError with code 'auth/invalid-provider-id'
  Required handlingValidate providerId format before calling createProviderConfig. OIDC provider IDs must start with 'oidc.' and SAML with 'saml.'. This is a synchronous validation error — no retry is useful. Return 400 Bad Request with clear description of required format.
  costlowin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[22]
• createProviderConfig · create-provider-config-quota-exceeded

  error
  WhenProject has reached the maximum number of SAML or OIDC provider configurations
  ThrowsFirebaseAuthError with code 'auth/quota-exceeded'
  Required handlingCatch and surface this as a billing/plan limit error. The project has hit the GCIP provider config limit. Do not retry — the error persists until existing configs are deleted. Return 429 or 503 with explanation to the calling service.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[23]
• createProviderConfig · create-provider-config-insufficient-permission

  error
  WhenService account lacks Identity Platform Admin or required IAM role
  ThrowsFirebaseAuthError with code 'auth/insufficient-permission'
  Required handlingCatch and alert — this is a service account misconfiguration. The service account requires the 'Firebase Authentication Admin' or 'identitytoolkit.admin' IAM role. Do not retry. Return 500 Internal Server Error and alert on-call.
  costhighin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[23]
• updateProviderConfig · update-provider-config-not-found

  error
  WhenNo provider configuration exists for the given providerId
  ThrowsFirebaseAuthError with code 'auth/configuration-not-found'
  Required handlingCatch and handle this as a 404. The provider config was deleted or never created. Verify the providerId is correct and the config exists before updating. Do not retry with same ID — the error is permanent until the config is created.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[24]
• updateProviderConfig · update-provider-config-invalid-config

  error
  WhenupdatedConfig is null, not an object, or contains invalid field values
  ThrowsFirebaseAuthError with code 'auth/invalid-config'
  Required handlingValidate configuration object before calling updateProviderConfig. OIDC requires clientId, issuer, and clientSecret for code flow. SAML requires idpEntityId, ssoURL, and x509Certificates. Catch and return 400 Bad Request with specific field validation errors.
  costlowin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[24]
• deleteProviderConfig · delete-provider-config-not-found

  error
  WhenNo provider configuration exists for the given providerId
  ThrowsFirebaseAuthError with code 'auth/configuration-not-found'
  Required handlingTreat as idempotent in most cases — the config is already gone. If this is unexpected (e.g., double-delete race), log and handle gracefully. Do NOT surface this as an error to the end user in an admin UI — the outcome (config is gone) is the desired state.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[24]
• getProviderConfig · get-provider-config-not-found

  error
  WhenNo provider configuration exists for the given providerId
  ThrowsFirebaseAuthError with code 'auth/configuration-not-found'
  Required handlingCatch and handle as 404. This is a normal condition when checking if a provider is configured. Do not assume provider exists — always catch this error in admin management workflows.
  costlowin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[24]
• createTenant · create-tenant-invalid-tenant-id

  error
  WhentenantId in options is an empty string or invalid format
  ThrowsFirebaseAuthError with code 'auth/invalid-tenant-id'
  Required handlingValidate tenantId before calling createTenant. Tenant IDs must be non-empty strings. If using auto-generated IDs, omit the tenantId field and Firebase will generate one. Catch and return 400 Bad Request.
  costlowin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[22]
• createTenant · create-tenant-missing-display-name

  error
  WhendisplayName is required but missing from tenant options
  ThrowsFirebaseAuthError with code 'auth/missing-display-name'
  Required handlingAlways include a displayName when creating tenants. The displayName is required by GCIP for tenant creation and is used in the Firebase Console and audit logs. Catch and return 400 with field validation details.
  costlowin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[23]
• createTenant · create-tenant-quota-exceeded

  error
  WhenProject has reached the maximum number of tenants for the GCIP plan
  ThrowsFirebaseAuthError with code 'auth/quota-exceeded'
  Required handlingCatch and surface as a billing/capacity limit. Contact Google Cloud support to increase tenant quota. Do not retry — the error is persistent until quota is increased or existing tenants are deleted. Alert operations team immediately.
  costhighin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[23]
• updateTenant · update-tenant-not-found

  error
  WhenNo tenant exists for the provided tenantId
  ThrowsFirebaseAuthError with code 'auth/tenant-not-found'
  Required handlingCatch and handle as 404. Verify the tenantId is correct. This can occur if a tenant was deleted between reads. Do not retry — the tenant must be recreated if missing. Return 404 to calling service.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[22]
• updateTenant · update-tenant-invalid-tenant-type

  error
  WhenAttempting to change the tenant type (full_service vs lightweight) after creation
  ThrowsFirebaseAuthError with code 'auth/invalid-tenant-type'
  Required handlingTenant type cannot be changed after creation. Remove the tenantType field from update requests if the type is already set. This is a permanent constraint — the only fix is to delete and recreate the tenant.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[23]
• deleteTenant · delete-tenant-not-found

  warning
  WhenNo tenant exists for the provided tenantId
  ThrowsFirebaseAuthError with code 'auth/tenant-not-found'
  Required handlingTreat as idempotent — the tenant is already gone. In offboarding workflows, this is generally safe to ignore. Log the occurrence for audit trails (the tenant may have been deleted by a concurrent request or external process).
  costlowin prodimmediate exceptionusers seedegraded performancevisibilityvisible
  Sources[22]
• getTenant · get-tenant-not-found

  error
  WhenNo tenant exists for the provided tenantId
  ThrowsFirebaseAuthError with code 'auth/tenant-not-found'
  Required handlingCatch and handle as 404. Always check tenant existence before performing tenant-scoped operations. If tenantId comes from user input or external systems, validate it with getTenant before calling authForTenant(). Return 404 to calling service.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[23]
• setRules · set-rules-invalid-argument

  error
  Whensource is null, undefined, empty string, or not a string/Buffer/object
  ThrowsFirebaseDatabaseError with code 'database/invalid-argument'
  Required handlingValidate rules source before calling setRules. The source must be a non-empty string (rules JSON), a Buffer containing rules, or a parsed object. Never pass null or empty string. This is a synchronous validation — no network call is made.
  costlowin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[25]
• setRules · set-rules-permission-denied

  error
  WhenService account lacks firebaserules.rulesets.create IAM permission or Firebase Admin role
  ThrowsFirebaseDatabaseError with HTTP 403 / permission-denied
  Required handlingCatch and alert — this is a service account misconfiguration in the deployment environment. The service account requires the Firebase Admin SDK Service Agent role or firebaserules.rulesets.create permission. Do not retry. Alert the deployment pipeline — rules were NOT updated.
  costhighin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[25]
• getDownloadURL · get-download-url-no-token

  error
  WhenFile exists in Cloud Storage but has no Firebase download token. Files uploaded directly via Google Cloud Storage APIs (not Firebase SDK) do not have download tokens by default.
  ThrowsFirebaseError with code 'storage/no-download-token'
  Required handlingCatch and handle: create a download token by updating the file's metadata via the Firebase Console or by calling file.setMetadata() to add a firebaseStorageDownloadTokens metadata entry. Files uploaded via Firebase Client SDK automatically have tokens. Files uploaded via @google-cloud/storage SDK do NOT have tokens unless explicitly added. This is a common pitfall in hybrid upload architectures.
  costmediumin prodimmediate exceptionusers seelost datavisibilityvisible
  Sources[26]
• getDownloadURL · get-download-url-file-not-found

  error
  WhenFile does not exist in the Cloud Storage bucket
  ThrowsError with HTTP 404 from Google Cloud Storage API
  Required handlingCatch HTTP 404 errors — this occurs when the file path is incorrect, the file was deleted, or the bucket name is wrong. Always verify file existence before generating download URLs in critical workflows. Return 404 to the calling client.
  costmediumin prodimmediate exceptionusers seelost datavisibilityvisible
  Sources[26]

Sources

Every postcondition cites at least one of these. Numbered to match the footnotes above.

1. [1]firebase.google.com/docs/authhttps://firebase.google.com/docs/auth/admin/errors
2. [2]firebase.google.com/docs/authhttps://firebase.google.com/docs/auth/admin/verify-id-tokens
3. [3]firebase.google.com/docs/referencehttps://firebase.google.com/docs/reference/admin/error-handling
4. [4]firebase.google.com/docs/authhttps://firebase.google.com/docs/auth/admin/manage-users
5. [5]firebase.google.com/docs/authhttps://firebase.google.com/docs/auth/admin/custom-claims
6. [6]cloud.google.com/firestore/docshttps://cloud.google.com/firestore/docs/understand-error-codes
7. [7]firebase.google.com/docs/firestorehttps://firebase.google.com/docs/firestore/query-data/get-data
8. [8]firebase.google.com/docs/firestorehttps://firebase.google.com/docs/firestore/best-practices
9. [9]firebase.google.com/docs/firestorehttps://firebase.google.com/docs/firestore/manage-data/add-data
10. [10]firebase.google.com/docs/cloud-messaginghttps://firebase.google.com/docs/cloud-messaging/error-codes
11. [11]firebase.google.com/docs/cloud-messaginghttps://firebase.google.com/docs/cloud-messaging/send-message
12. [12]firebase.google.com/docs/cloud-messaginghttps://firebase.google.com/docs/cloud-messaging/send-message#send-messages-to-topics
13. [13]firebase.google.com/docs/databasehttps://firebase.google.com/docs/database/admin/start
14. [14]firebase.google.com/docs/databasehttps://firebase.google.com/docs/database/admin/save-data
15. [15]firebase.google.com/docs/authhttps://firebase.google.com/docs/auth/admin/create-custom-tokens
16. [16]firebase.google.com/docs/firestorehttps://firebase.google.com/docs/firestore/manage-data/transactions
17. [17]firebase.google.com/docs/cloud-messaginghttps://firebase.google.com/docs/cloud-messaging/manage-topics
18. [18]raw.githubusercontent.com/firebase/firebase-admin-nodehttps://raw.githubusercontent.com/firebase/firebase-admin-node/master/src/auth/auth-api-request.ts
19. [19]firebase.google.com/docs/authhttps://firebase.google.com/docs/auth/admin/manage-users#import_users
20. [20]raw.githubusercontent.com/firebase/firebase-admin-nodehttps://raw.githubusercontent.com/firebase/firebase-admin-node/master/src/remote-config/remote-config-api-client-internal.ts
21. [21]firebase.google.com/docs/remote-confighttps://firebase.google.com/docs/remote-config/use-config-rest#quotas
22. [22]github.com/firebase/firebase-admin-nodehttps://github.com/firebase/firebase-admin-node/blob/master/src/auth/auth-api-request.ts
23. [23]github.com/firebase/firebase-admin-nodehttps://github.com/firebase/firebase-admin-node/blob/master/src/utils/error.ts
24. [24]github.com/firebase/firebase-admin-nodehttps://github.com/firebase/firebase-admin-node/blob/master/src/auth/base-auth.ts
25. [25]github.com/firebase/firebase-admin-nodehttps://github.com/firebase/firebase-admin-node/blob/master/src/database/database.ts
26. [26]github.com/firebase/firebase-admin-nodehttps://github.com/firebase/firebase-admin-node/blob/master/src/storage/index.ts