LinkedIn
Instagram
WhatsApp
Telegrama
Gmail
Perspectivas
Google Agenda
Participe da comunidade do SlackLimites da API do Gmail em 2026: Cotas, Limites de Taxa, e Como Lidar com Eles
Referência de cota da API Gmail completa cobrindo limites por minuto, por usuário e diários, custos unitários por método, tratamento de erros 429 e um padrão de backoff exponencial pronto para produção para usuários autenticados.
async function withBackoff(fn, maxRetries = 5) { let delay = 1000; for (let i = 0; i < maxRetries; i++) { try { return await fn(); } catch (err) { if (err.code !== 429) throw err; const jitter = Math.random() * 500; await sleep(delay + jitter); delay *= 2; } }}Com escopo para a sessão do usuário autenticado
Unipile não mantém um arquivo paralelo dos dados da caixa de correio do Gmail. Todo o acesso ao e-mail é feito com escopo para a sessão do usuário autenticado que concedeu explicitamente o consentimento OAuth. Nenhum dado é armazenado independentemente além do que é necessário para atender a essa solicitação específica.
Intermediário técnico independente
Unipile atua como um intermediário técnico independente, fazendo chamadas à API do Gmail em nome de cada usuário autenticado individualmente. A Unipile não é parceira nem afiliada do Google. Nenhuma credencial é compartilhada entre usuários. Cada token OAuth pertence exclusivamente ao usuário que o concedeu.
Cadência é uma decisão do lado do cliente
A Unipile gerencia os limites de taxa e as restrições de cota da API do Gmail, conforme definido pelo Google. A frequência e o volume das chamadas de API feitas em nome de cada usuário é um decisão do lado do cliente. O Unipile trata erros de cota e aplica lógica de backoff, mas a cadência de chamadas permanece sob o controle do desenvolvedor.
Limites da API do Gmail em resumo
Antes de escrever uma única linha de lógica de retentativa, você precisa ter uma visão clara de todos os três eixos de cotas que o Google impõe. A tabela abaixo é a referência que você irá marcar: vazão por projeto, limites por usuário e o teto diário que reinicia à meia-noite, horário do Pacífico.
| Limite | Valor | Dimensão | Anotações |
|---|---|---|---|
| Limite de taxa da API do Gmail (unidades de cota) | 1.200.000 / min | Por projeto GCP | Compartilhado entre todos os usuários no projeto |
| Limite de taxa por usuário da API do Gmail | 6.000 / min | Por caixa de correio do usuário | Gatilho mais comum para 429 em produção |
| Cota diária | 80.000.000 por dia | Por projeto GCP | Reinicia à meia-noite, hora do Pacífico |
| Cota de envio do Gmail (Gmail gratuito) | 500 e-mails / dia | Por endereço do remetente | 2.000 / dia para o Google Workspace |
| Requisições simultâneas por caixa de correio | 50 | Por caixa de correio | Limite oculto - dispara 429 independentemente da cota |
| Solicitações em lote por chamada | 100 solicitações | Por chamada em lote | Use em lote para reduzir o consumo de unidades de cota |
| Tamanho máximo da mensagem (anexos) | 25 MB | Por mensagem | Incluindo cabeçalhos e corpo codificado |
Fonte: Documentação do Google Developers, API do Gmail - Limites de Uso (última verificação em maio de 2026). Os limites estão sujeitos a alterações; sempre verifique a página de cotas do seu console GCP para os valores atuais do seu projeto.
As três dimensões de cota
Os limites de uso da API do Gmail funcionam em três eixos independentes simultaneamente. Uma solicitação pode ser bloqueada mesmo que duas das três estejam boas. Entender a separação entre limites por projeto, por usuário e diários é o primeiro passo para escrever código resiliente para qualquer usuário autenticado.
Por projeto (GCP)
1.200.000 unidades/minEste é o teto agregado em todos os usuários dentro de um projeto GCP. Se você tiver 500 usuários autenticados fazendo chamadas para a API do Gmail simultaneamente, o consumo de cota de todos eles conta contra esse único bucket. Atingi-lo aciona um limiteDeTaxaExcedido O equivalente diário é 80 milhões de unidades, reiniciando à meia-noite, horário do Pacífico.
Por usuário (por caixa de correio)
6.000 unidades/minEste limite se aplica independentemente a cada usuário autenticado. Mesmo que seu projeto tenha margem de cota, um único usuário bombardeando sua própria caixa de correio com polling rápido acionará um userTaxaLimiteExcedida 429. Em aplicativos multi-inquilino, este é o limite que é acionado com mais frequência: é por usuário, não compartilhado.
Cota diária
80.000.000 unidades/diaO limite diário também é por projeto. Ao contrário dos períodos de um minuto que se recuperam automaticamente após 60 segundos, atingir o cota diária significa que não haverá mais acesso à API até a meia-noite no horário do Pacífico. O erro é LimiteDiárioExcedido. Você pode solicitar um aumento de cota através do console do GCP - abordamos isso na seção de multilocação.
Importante: Os limites de taxa da API do Gmail acima são medidos em "unidades de cota", e não em contagens brutas de requisições. Um mensagens.enviar a ligação custa 100 unidades, enquanto um mensagens.listar custa apenas 5. Isso significa que seu orçamento prático de solicitação varia significativamente dependendo de quais métodos você chama. Consulte a tabela de custo unitário na próxima seção. Observe também que Verificação de escopo OAuth os erros do fluxo de consentimento são completamente separados desses erros de cota de tempo de execução.
Custo unitário da cota por método
Nem todas as chamadas da API do Gmail são iguais. O Google conta o uso de cotas em "unidades" abstratas, e cada método tem um custo diferente. Saber esses custos permite que você calcule sua capacidade real de requisições e otimize os endpoints que chama. O limite de taxa por usuário da API do Gmail de 6.000 unidades/min se comporta de maneira muito diferente dependendo da sua mistura de chamadas.
| Método | Custo Unitário | Requisições / min (por usuário) | Dica de otimização |
|---|---|---|---|
| mensagens.enviar | 100 | 60 envios/min máx. | Custo mais alto - usar rascunho + enviar apenas quando necessário |
| mensagens.inserir | 25 | 240/min máx | Inserindo na caixa de correio - menor que enviar |
| threads.get | 10 | 600/min no máximo | Prefira threads.get em vez de multiple messages.get |
| messages.get | 5 | 1.200/min máx | Adicionar campos= resposta parcial para manter o custo em 5 |
| mensagens.listar | 5 | 1.200/min máx | Use history.list em vez de padrões de sincronização |
| threads.list | 5 | 1.200/min máx | Paginare com maxResults para reduzir chamadas |
| usuários.histórico.lista | 2 | 3.000/min máx | Melhor para sincronização incremental - menor custo de polling |
| rótulos.lista | 1 | 6.000/min máx | Armazene o resultado em cache - os rótulos raramente mudam |
| mensagens.modificar | 5 | 1.200/min máx | Use batchModify para atualizações em massa de rótulos |
| mensagens.anexos.obter | 5 | 1.200/min máx | Buscar anexos somente quando explicitamente necessários |
Dica profissional: Você pode usar o campos= parâmetro de consulta para respostas parciais em qualquer método. Solicitar apenas os campos que seu aplicativo precisa não reduz o custo unitário bruto, mas reduz drasticamente o tamanho do payload da resposta e a latência - um ganho que vale a pena quando você está perto dos limites de cota da API do Gmail. Teste suas consultas interativamente usando o Gmail OAuth Playground antes de enviar para produção.
O limite oculto de 50 requisições simultâneas por caixa de correio
Há um limite que a maioria dos tutoriais sobre a API do Gmail nunca menciona, mas que é a causa de erros 429 misteriosos em aplicativos multithread ou assíncronos: o Gmail impõe um limite máximo de 50 requisições simultâneas em voo por caixa de correio. Este limite é completamente independente do seu orçamento de unidades de cota. Você pode estar com 500 unidades de cota de 6.000 disponíveis e, ainda assim, receber um 429 se tiver 51 solicitações abertas simultaneamente na caixa de correio do mesmo usuário autenticado.
Por que isso surpreende os desenvolvedores
Frameworks assíncronos como Node.js Promise.all() ou Python asyncio.gather() torne trivialmente fácil disparar mais de 100 requisições concorrentes. Quando você processa um sync de caixa de correio e distribui para buscar 200 mensagens simultaneamente em nome de um único usuário autenticado, o Gmail vê 200 conexões TCP abertas em uma única caixa de correio e imediatamente limita. O painel de cotas no GCP mostrará muitas unidades restantes - o limite de 50 conexões simultâneas não é exposto como uma métrica de cota.
Quando disparar
O limite de 50 conexões simultâneas é acionado durante operações de sincronização em massa de caixas de correio: buscando grandes tópicos, baixando anexos para muitas mensagens simultaneamente ou paginando através de grandes contagens de rótulos enquanto também processa resultados de forma concorrente. Qualquer código que inicie mais de 50 solicitações em andamento para a mesma caixa de correio atingirá este limite.
Como consertar isso
Use um limitador de concorrência (semáforo) com escopo por usuário autenticado. Em Node.js, bibliotecas como p-limite funciona bem. Em Python, um asyncio.Semaphore(40) com uma margem segura abaixo de 50 evita o estouro. Mantenha sua concorrência por usuário em 40 ou abaixo para margem de segurança.
// p-limit mantém a concorrência por usuário abaixo de 40import pLimite from 'p-limite';// Uma instância de limiter por usuário autenticado (chaveada por userId)const userLimiters = new Map();função obterLimitador(userId) { se (!limitadoresDeUsuário.tem(userId)) { Limitadores de usuário.definir(idUsuario, pLimite(40)); } return Limitadores de usuário.obter(identificadorDoUsuario);}// Envolver cada chamada da API do Gmail com o limitador do usuárioasync function buscarMensagem(gmail, userId, messageId) { const limite = obterLimitador(identificadorDoUsuario); return limite(() => gmail.users.messages.obter({ userId: "eu, id: messageId, campos: 'id,threadId,payload.headers,snippet' }));}Decodificando os erros: 429 vs 403
A API do Gmail retorna dois códigos de status HTTP diferentes para problemas de cota e acesso: 429 (Muitas Solicitações) e 403 (Proibido). Dentro desses dois códigos, existem quatro motivos de erro distintos, cada um com uma causa raiz e uma resolução diferentes. Confundí-los desperdiça tempo de depuração. Observação: erros de fluxo OAuth como concessão_inválida são erros de token de atualização eles são completamente separados desses limites de taxa da API do Gmail em tempo de execução.
| Código HTTP | Motivo do erro | Causa | Consertar |
|---|---|---|---|
| 429 | limiteDeTaxaExcedido | Excedeu 1,2 milhão de unidades de cota/min no nível do projeto GCP. Todos os usuários autenticados no projeto atingiram coletivamente o limite. | Retrocesso exponencial com jitter. Aguarde e tente novamente. Longo prazo: fragmentar em múltiplos projetos GCP ou solicitar aumento de cota. |
| 429 | userTaxaLimiteExcedida | Um único usuário autenticado excedeu 6.000 unidades de cota/min, OU excedeu 50 solicitações simultâneas para sua caixa de correio. O 429 de produção mais comum. | Fila por usuário com limitador de concorrência. Aplique o padrão semáforo (máximo de 40 concorrentes). Adicione backoff exponencial em retentativas 429. |
| 403 | LimiteDiárioExcedido | O projeto GCP consumiu todas as 80 milhões de unidades de cota diária antes da meia-noite no Pacífico. Não pode ser retentado até o reset. Esta é uma parada definitiva. | Aguarde a meia-noite do reset do Pacífico ou solicite um aumento de cota através do console do GCP. Implemente o orçamento diário de cota por usuário em seu aplicativo. |
| 403 | cotaExcedida | Uma subcota específica foi excedida. Também pode indicar que a cota de envio do Gmail (500 e-mails/dia gratuito, 2.000 Workspace) foi atingida para um endereço de remetente específico. | Verifique qual cota. Para enviar cota: mude o endereço de envio ou aguarde 24h. Para outras sub-cotas: identifique a métrica específica no painel de cotas do GCP. |
Limite máximo do projeto atingido: 1,2 milhão de unidades de cota/min para todos os usuários.
Correção: Backoff exponencial + jitter. Longo prazo: múltiplos projetos GCP ou solicitação de aumento de cota.
Usuário único excedeu 6.000 unidades/min OU 50 requisições simultâneas. O 429 mais comum.
Correção: Fila por usuário + semáforo (máx. 40 concorrentes). Adicionar retentativa com backoff.
Projeto consumiu todas as 80 milhões de unidades de cota diária. Parada total até a meia-noite do Pacífico.
Correção: Aguarde a redefinição ou solicite um aumento de cota através do console do GCP.
Cota de envio do Gmail (500/dia grátis, 2.000 Workspace) atingida para o remetente.
Correção: Verificar o painel do GCP para cota específica. Para enviar: trocar de endereço ou esperar 24h.
concessão_inválida, acesso_negadoe cliente_invalido vêm da camada de troca de tokens OAuth, e não da aplicação de cotas da API do Gmail. Elas são abordadas separadamente em Guia de erros do Google OAuth. Se você vir um 401 Não Autorizado, isso também é um problema de autenticação - verifique seu Verificação de aplicativo OAuth status e se o token de atualização expirou. Manuseio pronto para produção: backoff exponencial + jitter
Exponential backoff é a única resposta correta para um 429 da API do Gmail. Tentar novamente imediatamente piora o problema: você adiciona mais solicitações a uma janela de cota já limitada. Adicionar jitter aleatório evita o problema do "thundering herd", onde todos os clientes em uma frota tentam novamente no mesmo momento. Abaixo estão implementações completas e testadas em produção em Node.js e Python.
Atraso inicial
Comece com 1.000ms na primeira tentativa. Nunca tente novamente imediatamente após um 429.
Multiplicador exponencial
Atraso dobrado a cada tentativa: 1s, 2s, 4s, 8s, 16s. Limite máximo de 32-64 segundos.
Tremulação aleatória
Adiciona jitter aleatório de 0 a 500 ms para evitar novas tentativas sincronizadas entre workers concorrentes.
// gmail-backoff.js - production-ready exponential backoff + jitter// Handles rateLimitExceeded and userRateLimitExceeded (gmail api rate limits)const sleep = (ms) => new Promise(r => setTimeout(r, ms));async function withGmailBackoff(fn, { maxRetries = 5, initialDelay = 1000, maxDelay = 32000, jitter = 500} = {}) { let delay = initialDelay; for (let attempt = 0; attempt < maxRetries; attempt++) { try { return await fn(); } catch (err) { const code = err?.code || err?.response?.status; const reason = err?.errors?.[0]?.reason || ''; // Only retry on quota errors - not on 403 dailyLimitExceeded const isRetryable = code === 429 || reason === 'rateLimitExceeded' || reason === 'userRateLimitExceeded'; if (!isRetryable || attempt === maxRetries - 1) throw err; const wait = Math.min(delay + Math.random() * jitter, maxDelay); await sleep(wait); delay *= 2; } }}// Usage: on behalf of each authenticated userconst message = await withGmailBackoff(() => gmail.users.messages.get({ userId: 'me', id: messageId }));# gmail_backoff.py - recuo exponencial + jitter para limites de taxa da API do Gmailimport asyncio, randomfrom googleapiclient.errors import HttpErrorasync def com_retorno_do_gmail( fn, max_retries=5, atraso_inicial=1.0, max_atraso=32.0, jitter=0.5): "Envolva qualquer chamada da API do Gmail com backoff exponencial + jitter aleatório. Trata limites de taxa da API do Gmail: rateLimitExceeded e userRateLimitExceeded. """ atraso = atraso_inicial para tentativa em range(max_retentativas): tentar: return fn() A função # é uma chamada do cliente sincronizado do Gmail exceto HttpError como e: status = e.resp.status motivo = e.detalhes_do_erro[0].obter('razão', '') se e.detalhes_erro senão '' # Repetir tentativa no 429; NÃO repetir tentativa no dailyLimitExceeded tentável = status == 429 ou motivo em ( 'taxaLimiteExcedida', 'LimiteDeTaxaDoUsuárioExcedido' ) se não tentativa ou tentativa == max_tentativas - 1: levantar espere = meu(atraso + aleatório.uniforme(0, jitter), max_delay) await asyncio.dormir(espere) atraso *= 2Estratégias para ficar abaixo do limite
O Backoff lida com a situação de emergência. Essas estratégias proativas evitam, desde o início, que você atinja os limites de cota da API do Gmail. Elas estão listadas da maior para a menor influência no consumo da sua cota. Combinar duas ou três delas pode reduzir seus custos unitários em 80% em cargas de trabalho típicas com grande volume de leituras.
Fila por usuário autenticado
Manter uma fila de requisições separada por usuário autenticado. Nunca misture solicitações de usuários diferentes em uma fila compartilhada. Isso isola a exposição ao limite de taxa por usuário e permite um enfileiramento justo: se um usuário disparar um 429, apenas a fila dele pausará - os outros continuarão na velocidade máxima. Use Redis ou uma fila na memória com um balde de tokens por usuário.
use history.list em vez de messages.list para sincronizar
Pesquisa de opinião mensagens.listar usar um temporizador é o erro mais comum nos limites de uso da API do Gmail. usuários.histórico.lista custa apenas 2 unidades (em comparação com 5 para messages.list) e retorna apenas a diferença desde o seu último ponto de sincronização. Para aplicativos com grande volume de leitura que sincronizam caixas de correio grandes, essa opção por si só pode reduzir o consumo de cota em 60%. Armazene o idHistórico de cada resposta como seu cursor. Emparelhe com Notificações Push do Gmail (Pub/Sub) para sincronização quase em tempo real.
Chamadas em lote de API
A API do Gmail suporta requisições em lote: combine até 100 pedidos individuais em uma única chamada HTTP. Cada sub-requisição ainda conta seu custo unitário normal, mas você reduz a sobrecarga TCP e os "slots" de limite de taxa consumidos. Isso é particularmente eficaz para messages.get operações onde você precisa buscar muitas mensagens de um delta de sincronização. Verifique o Guia em lote do Gmail para detalhes de implementação.
Use respostas parciais (campos=)
Todo método da API do Gmail suporta a campos= parâmetro para solicitar apenas as propriedades necessárias. Embora isso não reduza o custo unitário da solicitação, diminui a carga útil da resposta em 60-90% e melhora a latência. Para um messages.get retornando apenas id,idDoTópico,cabeçalhosDoPayload,trecho, a carga útil cai de mais de 40 KB para menos de 2 KB. Menos rede = iteração mais rápida = mais espaço antes de atingir o teto da cota diária da API do Gmail.
Push vs. Poll: o modelo de sincronização correto
5 unidades por enquete + N x 5 unidades para buscar cada nova mensagem. Para 100 usuários x intervalo de 30s = 1 milhão de unidades/hora apenas em sobrecarga de enquete.
2 unidades por consulta; retorna apenas as alterações desde a última sincronização. 60% é mais barato do que a consulta ao `messages.list` para obter o mesmo resultado.
Custo de cota zero para entregas. O Google envia uma notificação quando uma caixa de correio é alterada – você busca apenas a diferença. Requer um endpoint de webhook público. Ideal para aplicações quase em tempo real.
Escalabilidade multi-inquilino e solicitação de aumento de cota
Assim que você ultrapassa um punhado de contas vinculadas, as cotas da API do Gmail se tornam uma preocupação arquitetural. Esta seção cobre o fragmentação (sharding) de projetos do GCP para implantações em larga escala e o processo passo a passo para solicitar um aumento de cota da API do Gmail ao Google.
Sharding de projetos no GCP
A cota de 1,2 milhão de unidades por minuto é por projeto GCP. Se você tem 1.000 usuários autenticados sincronizando ativamente, você pode dividi-los em dois projetos GCP para dobrar sua capacidade efetiva em nível de projeto. Cada projeto precisa de suas próprias credenciais de cliente OAuth e tela de consentimento. Usuários vinculados ao projeto A não podem usar a cota do projeto B. Isso é particularmente útil para cenários de sincronização de e-mail de alto volume onde o limite diário da cota da API do Gmail é uma preocupação. Monitore o uso da sua cota no console do GCP para saber quando o particionamento é necessário.
Solicitando um aumento de cota
O Google concede aumentos de cota mediante solicitação, mas eles levam tempo (normalmente de 3 a 5 dias úteis para análise inicial, até 2 semanas para aumentos significativos). Envie através do GCP Console: APIs e Serviços > Gmail API > Cotas > "Solicitar cota maior". O Google exige uma justificativa detalhada. Itens chave a incluir: usuários ativos diários estimados, solicitações médias por usuário por dia, detalhamento por método (mensagens.enviar vs mensagens.listar etc.), e o caso de uso de produção. Solicitações vagas são negadas. Forneça números concretos da sua telemetria de staging.
Monitorar e orçar a cota diária
Implemente o rastreamento de orçamento de cotas por usuário autenticado em sua própria camada de dados. Rastreie unidadesDeCotaUsadas para cada usuário diariamente. Quando um usuário se aproximar de 70-80% de seu orçamento diário por usuário, mude do modo de sincronização ativa para o modo somente push para esse usuário pelo restante do dia. Isso evita que um usuário com alto volume de uso esgote de forma desproporcional a cota diária do projeto. A frequência com que você aloca cota por usuário é uma decisão do lado do cliente em termos do seu design de aplicação.
O que incluir em sua solicitação de aumento de cota
Uso base atual: "Atualmente usamos X milhões de unidades/dia em Y usuários ativos."
Projeção de crescimento: "Em 6 meses, esperamos Z usuários, exigindo aproximadamente W milhão de unidades/dia."
Caso de uso: "Nosso produto lê o Gmail para alimentar [sincronização de CRM / caixa de entrada do ATS / análise de e-mail]. Os usuários se autenticam individualmente via OAuth."
Detalhamento do método: ""Métodos principais: messages.list (40%), messages.get (35%), history.list (20%), messages.send (5%).""
Como a Unipile gerencia a limitação do Gmail em nome do usuário autenticado
Construir toda a infraestrutura de throttling descrita neste guia — filas por usuário, semáforos, backoff exponencial, orçamento de cota diária, gerenciamento de projetos do GCP — leva semanas e exige manutenção contínua. A Unipile cuida de tudo isso como um intermediário técnico independente, assim sua equipe foca na lógica do produto, não na encanamento de cotas. O acesso à API do Gmail via Unipile não é afiliado, endossado ou patrocinado pelo Google.
Backoff exponencial gerenciado + jitter
Sempre que uma chamada da API do Gmail é feita em nome de cada usuário autenticado passa pela camada de backoff do Unipile. erros 429 são transparentes para seu código: o Unipile tenta novamente automaticamente com backoff exponencial completo e jitter, exibindo apenas o sucesso eventual ou um erro limpo após tentativas máximas.
Isolamento de fila por usuário
A Unipile mantém isolamento rigoroso por usuário. Um usuário autenticado com limite de taxa nunca afeta a taxa de transferência de outro usuário. Cada Conta vinculada possui sua própria fila com limites de concorrência individuais, garantindo alocação justa de recursos em toda a sua base de usuários.
Modelo Unificado: Gmail + Outlook + IMAP
A mesma lógica de limitação se aplica uniformemente a Gmail, Perspectivas (Microsoft 365 e Exchange Online), e IMAP. Sua aplicação usa uma API padronizada, independentemente de qual provedor de e-mail o usuário autenticado tenha vinculado. Nenhum código específico de limite de taxa do provedor para manter.
Em conformidade com o GDPR, alinhado com o SOC2
Os dados acessados através do Unipile são com escopo para a sessão do usuário autenticado quem concedeu o consentimento OAuth. Nenhum arquivo paralelo, nenhum armazenamento de longo prazo de dados da caixa de correio além dos requisitos da sessão. Alinhamento GDPR e SOC2 incorporado.
// Com Unipile: sem backoff, sem semáforos, sem rastreamento de cotas// Unipile lida com todos os limites de taxa da API do Gmail como um intermediário técnico independenteimport UnipileClient from '@unipile/node-sdk';const cliente = new UnipileClient({ apiKey: process.env.UNIPILE_API_KEY, baseUrl: 'https://api3.unipile.com:13613'});// Lista mensagens para a conta Gmail vinculada de um usuário autenticado// Limitação, recuo e isolamento por usuário tratados no lado do servidor pela Unipileasync function obterEmailsRecentes(accountId) { const mensagens = await client.messaging.listarMensagens({ account_id: account_id, // conta vinculada do usuário autenticado limite: 25 }); return mensagens;}// Funciona de forma idêntica para contas vinculadas do Gmail, Outlook e IMAP// Mesmo código, zero tratamento de limite de taxa específico do provedorLimites de Taxa da API do Gmail - Perguntas Frequentes
Respostas para as perguntas mais comuns sobre limites de taxa da API do Gmail, unidades de cota, erros 429 e escalonamento da sua integração.
A API do Gmail impõe limites em três dimensões simultaneamente. No nível do projeto: 1.200.000 unidades de cota por minuto compartilhada entre todos os usuários, e 80.000.000 unidades de cota por dia. No nível do usuário: 6.000 unidades de cota por minuto por caixa de correio. Há também um limite oculto de 50 requisições simultâneas por caixa de correio o que pode gerar um 429 mesmo quando você está bem abaixo do teto de unidades da cota. Cada método tem um custo de unidade diferente - mensagens.enviar custa 100 unidades enquanto mensagens.listar custa apenas 5.
Implementar backoff exponencial com jittercomece em 1.000ms na primeira tentativa, dobre a cada tentativa, adicione jitter aleatório de 0-500ms, limite em 32.000ms. Nunca retente imediatamente. Adicione um limitador de concorrência com escopo por usuário autenticado, mantendo as solicitações em andamento abaixo de 40 por caixa de correio. Use um fila por usuário para que um usuário com limitação de taxa não afete outros. A longo prazo, mudar a sonagem de mensagens.listar (5 unidades) para histórico.listar (2 unidades) e considerar as Notificações Push do Gmail para eliminar completamente a verificação periódica.
A API do Gmail a cota diária é de 80.000.000 unidades de cota por projeto GCP, resetando à meia-noite, horário do Pacífico. Este limite retorna um 403 LimiteDiárioExcedido erro - diferente dos erros 429 por minuto, este não pode ser retentado até a reinicialização diária. Para aumentá-lo: Console do GCP > APIs e Serviços > Gmail API > Quotas > Solicitar cota maior. Inclua o uso atual, projeções de crescimento e seu caso de uso. A aprovação geralmente leva de 3 a 5 dias úteis.
O Gmail A cota de envio é de 500 e-mails por dia para contas gratuitas do Gmail e 2.000 emails por dia para contas do Google Workspace. Este limite é por endereço de remetente e é separado do orçamento de unidades de cota da API. Cada mensagens.enviar A chamada também custa 100 unidades de quota, então com o limite de 6.000 unidades/min por usuário, você pode enviar no máximo 60 e-mails por minuto antes de atingir o limite de taxa da API do Gmail por usuário – mas o limite diário de 500/2.000 será provavelmente atingido primeiro para casos de uso típicos.
limiteDeTaxaExcedido significa que todo o projeto GCP ultrapassou 1.200.000 unidades/min de cota – todos os usuários autenticados juntos. userTaxaLimiteExcedida significa que um único usuário excedeu 6.000 unidades de cota/min ou enviou mais de 50 requisições simultâneas para a caixa de correio deles. Em aplicativos multi-tenant de produção, userTaxaLimiteExcedida é muito mais comum porque usuários individuais podem atingir seus limites independentemente, independentemente do espaço livre geral do projeto. Ambos retornam HTTP 429 e ambos respondem ao backoff exponencial.
Navegar para Console do GCP > APIs e Serviços > Gmail API > Cota e clique em "Solicitar cota maior". Sua solicitação deve incluir uma justificativa concreta: linha de base de uso diário atual, projeção de crescimento de usuários para 6 meses, descrição de como os usuários se autenticam individualmente via OAuth e um detalhamento dos métodos de API por proporção. Solicitações vagas são negadas. Certifique-se também de que seu aplicativo OAuth verificado - aplicativos não verificados são limitados a 100 usuários de teste, independentemente da cota. A revisão geralmente leva de 3 a 5 dias úteis para a resposta inicial.
mensagens.enviar custos 100 unidades de cota por chamada - o método mais caro da API do Gmail. Com o limite por usuário de 6.000 unidades/min, você pode enviar no máximo 60 e-mails por minuto por usuário autenticado. Para comparação: messages.get custa 5 unidades (1.200 chamadas/min), histórico.listar custa 2 unidades (3.000 chamadas/min), e rótulos.lista custa 1 unidade (6.000 chamadas/min). Para alcance de alto volume, considere se seu caso de uso realmente requer chamadas mensagens.enviar ou se é mais eficiente criar rascunhos e enviar em lotes.
A Unipile acessa apenas os dados explicitamente solicitados pela sua aplicação, com escopo para a sessão do usuário autenticado quem concedeu o consentimento OAuth. Não há um arquivo paralelo, nem um armazenamento independente de longo prazo dos dados da caixa de correio além do que é necessário para atender à solicitação atual da API. Os dados de cada usuário autenticado são isolados: a Unipile atua como um intermediário técnico independente em nome apenas desse usuário específico.
A frequência e o volume de chamadas de API feitas em nome de cada usuário autenticado é um decisão do lado do cliente. O Unipile gerencia a infraestrutura de backoff e fila, mas seu aplicativo determina com que frequência solicitar dados. O Unipile apresenta erros de cota de forma transparente e aplica lógica de retentativa, mas a cadência geral de chamadas — incluindo quantos usuários sincronizam simultaneamente e com que frequência — permanece sob seu controle como desenvolvedor que constrói sobre o Unipile.
Não. A Unipile é não afiliado, endossado ou patrocinado pelo Google. A Unipile é um intermediário técnico independente que realiza chamadas à API do Gmail em nome de usuários autenticados que concederam consentimento OAuth individualmente por meio de suas próprias contas do Google. Gmail é uma marca registrada da Google LLC. Todas as cotas, limites de taxa e políticas da API do Gmail são definidas pelo Google e estão sujeitas a alterações independentemente da Unipile.
Perguntas sobre limites da API do Gmail e integração com Unipile? Nossa equipe está aqui para ajudar.
O Guia Completo da API de E-mail para Desenvolvedores
Os limites do Gmail são uma peça do quebra-cabeça da API de e-mail. O guia principal cobre os padrões de integração do Gmail, Outlook e IMAP de ponta a ponta.
BR 
EN 
FR 
ES 
DE 
IT 
NL 
PL 
TR