A API do Gmail retorna dois níveis de informações de erro:
- Códigos e mensagens de erro HTTP no cabeçalho.
- Um objeto JSON no corpo da resposta com mais detalhes que podem ajudar a determinar como lidar com o erro.
Os apps do Gmail precisam capturar e processar todos os erros que podem ser encontrados ao usar a API REST. Este guia fornece instruções sobre como resolver erros específicos da API.
Resolver um erro 400: solicitação inválida
Esse erro pode ser resultado dos seguintes erros no seu código:
- Um campo ou parâmetro obrigatório não foi fornecido.
- O valor fornecido ou uma combinação de campos fornecidos é inválido.
- Anexo inválido.
Confira a seguir um exemplo de representação JSON desse erro:
{
"error": {
"code": 400,
"errors": [
{
"domain": "global",
"location": "orderBy",
"locationType": "parameter",
"message": "Sorting is not supported for queries with fullText terms. Results are always in descending relevance order.",
"reason": "badRequest"
}
],
"message": "Sorting is not supported for queries with fullText terms. Results are always in descending relevance order."
}
}
Para corrigir esse erro, verifique o campo message e ajuste o código de acordo com isso.
Resolver um erro 401: credenciais inválidas
Um erro 401 indica que o token de acesso que você está usando expirou ou é inválido. Esse erro também pode ser causado pela falta de autorização para os escopos solicitados. Confira a seguir a representação JSON desse erro:
{
"error": {
"errors": [
{
"domain": "global",
"reason": "authError",
"message": "Invalid Credentials",
"locationType": "header",
"location": "Authorization",
}
],
"code": 401,
"message": "Invalid Credentials"
}
}
Para corrigir esse erro, atualize o token de acesso usando o token de atualização de longa duração. Se você estiver usando uma biblioteca de cliente, ela vai processar automaticamente a atualização do token. Se isso falhar, direcione o usuário pelo fluxo OAuth, conforme descrito em Como autorizar seu app com o Gmail.
Para mais informações sobre os limites do Gmail, consulte Limites de uso.
Resolver um erro 403: limite de uso excedido
Um erro 403 ocorre quando um limite de uso é excedido ou o usuário não
tem os privilégios corretos. Para determinar o tipo específico de erro, avalie
o campo reason do JSON retornado. Esse erro ocorre nas seguintes
situações:
- O limite diário foi excedido.
- O limite de taxa do usuário foi excedido.
- O limite de taxa do projeto foi excedido.
- O app não pode ser usado no domínio do usuário autenticado.
Para mais informações sobre os limites do Gmail, consulte Limites de uso.
Resolver um erro 403: limite diário excedido
Um erro dailyLimitExceeded indica que o limite de API de cortesia do seu
projeto foi atingido. Confira a seguir a representação JSON desse erro:
{
"error": {
"errors": [
{
"domain": "usageLimits",
"reason": "dailyLimitExceeded",
"message": "Daily Limit Exceeded"
}
],
"code": 403,
"message": "Daily Limit Exceeded"
}
}
Para corrigir esse erro, siga as etapas abaixo:
- Acesse o Console de APIs do Google.
- Selecione o projeto.
- Clique na guia Cotas.
- Solicite cota extra. Para mais informações, consulte Solicitar mais cota.
Para mais informações sobre os limites do Gmail, consulte Limites de uso.
Resolver um erro 403: o limite de taxa de usuários foi excedido
Um erro userRateLimitExceeded indica que o limite por usuário foi
atingido. Confira a seguir a
representação JSON desse erro:
{
"error": {
"errors": [
{
"domain": "usageLimits",
"reason": "userRateLimitExceeded",
"message": "User Rate Limit Exceeded"
}
],
"code": 403,
"message": "User Rate Limit Exceeded"
}
}
Para corrigir esse erro, tente otimizar o código do aplicativo para fazer menos solicitações ou tentar novamente. Para informações sobre como repetir solicitações, consulte Repetir solicitações com falha para resolver erros.
Para mais informações sobre os limites do Gmail, consulte Limites de uso.
Resolver um erro 403: limite de taxa excedido
Um erro rateLimitExceeded indica que o usuário atingiu a taxa máxima de solicitações
da API Gmail. Esse limite varia de acordo com o tipo de solicitação.
Confira a seguir a representação JSON desse erro:
{
"error": {
"errors": [
{
"domain": "usageLimits",
"message": "Rate Limit Exceeded",
"reason": "rateLimitExceeded",
}
],
"code": 403,
"message": "Rate Limit Exceeded"
}
}
Para corrigir esse erro, tente novamente as solicitações com falha.
Para mais informações sobre os limites do Gmail, consulte Limites de uso.
Resolva um erro 403: o app com o ID {appId} não pode ser usado no domínio do usuário autenticado
Um erro domainPolicy ocorre quando a política do domínio do usuário não permite
o acesso ao Gmail pelo seu app. Confira a representação JSON
deste erro:
{
"error": {
"errors": [
{
"domain": "global",
"reason": "domainPolicy",
"message": "The domain administrators have disabled Gmail apps."
}
],
"code": 403,
"message": "The domain administrators have disabled Gmail apps."
}
}
Para corrigir esse erro, siga as etapas abaixo:
- Informe ao usuário que o domínio não permite que o app acesse o Gmail.
- Peça ao usuário para entrar em contato com o administrador do domínio e solicitar acesso ao app.
Resolver um erro 429: Muitas solicitações
Um erro 429 "Solicitações em excesso" pode ocorrer devido a limites diários por usuário (incluindo limites de envio de e-mail), limites de largura de banda ou um limite de solicitações simultâneas por usuário. Confira a seguir informações sobre cada limite. No entanto, cada limite pode ser resolvido tentando repetir solicitações com falha ou dividindo o processamento em várias contas do Gmail. Os limites por usuário não podem ser aumentados por qualquer motivo. Para mais informações sobre limites, consulte Limites de uso.
Limites de envio de e-mails
A API Gmail aplica os limites diários padrão de envio de e-mails. Esses limites diferem para usuários Google Workspace pagantes e usuários do teste do gmail.com. Para esses limites, consulte Limites de envio do Gmail no Google Workspace.
Esses limites são por usuário e compartilhados por todos os clientes do usuário, sejam
clientes de API, clientes nativos/da Web ou MSA SMTP. Se esses limites forem
excedidos, um erro HTTP 429 Too Many Requests "Limite de taxa de usuário excedido"
"(Envio de e-mail)" será retornado com tempo para tentar novamente.
O excesso dos limites diários pode resultar nesses tipos de erros por
várias horas antes que a solicitação seja aceita.
O pipeline de envio de e-mails é complexo: quando o usuário excede a cota, pode haver um atraso de vários minutos até que a API comece a retornar respostas de erro 429. Portanto, não é possível presumir que uma resposta 200 significa que o e-mail foi enviado.
Limites de largura de banda
A API tem limites de largura de banda de upload e download por usuário que são iguais, mas independentes do IMAP. Esses limites são compartilhados entre todos os clientes da API do Gmail para um determinado usuário.
Esses limites geralmente são atingidos apenas em situações excepcionais ou abusivas.
Se esses limites forem excedidos, um erro HTTP 429 Too Many Requests
"Limite de taxa de usuário excedido" será retornado com um tempo para nova tentativa.
O excesso dos limites diários pode resultar nesses tipos de erros
por várias horas antes que a solicitação seja aceita.
Solicitações simultâneas
A API Gmail impõe um limite de solicitação simultânea por usuário, além do limite de taxa por usuário. Esse limite é compartilhado por todos os clientes da API do Gmail que acessam um determinado usuário e garante que nenhum cliente da API esteja sobrecarregando uma caixa de e-mails do Gmail ou o servidor de back-end.
Fazer muitas solicitações paralelas para um único usuário ou enviar lotes com um
grande número de solicitações pode acionar esse erro. Um grande número de
clientes de API independentes acessando a caixa de e-mails do usuário do Gmail simultaneamente também pode
acionar esse erro. Se esse limite for excedido, um erro HTTP 429 Too Many Requests
"Too many concurrent requests for user" será retornado.
Resolver um erro 500: erro de back-end
Uma backendError ocorre quando um erro inesperado surge durante o processamento da
solicitação.
{
"error": {
"errors": [
{
"domain": "global",
"reason": "backendError",
"message": "Backend Error",
}
],
"code": 500,
"message": "Backend Error"
}
}
Para corrigir esse erro, tente novamente as solicitações com falha. Confira a seguir uma lista de erros 500:
- 502 Bad Gateway
- 503 Service Unavailable
- 504 Gateway Timeout
Tentar novamente solicitações com falha para resolver erros
É possível repetir periodicamente uma solicitação com falha em um período cada vez maior para processar erros relacionados a limites de taxa, volume de rede ou tempo de resposta. Por exemplo, você pode tentar novamente uma solicitação com falha após um segundo, depois dois segundos e, em seguida, quatro segundos. Esse método é chamado de espera exponencial e é usado para melhorar o uso da largura de banda e maximizar a capacidade de solicitações em ambientes simultâneos.
Inicie os períodos de nova tentativa pelo menos um segundo após o erro.
Conferir ou mudar os limites de uso e aumentar a cota
Para ver ou alterar limites de uso do projeto ou para solicitar um aumento da cota, faça o seguinte:
- Se você ainda não tem uma conta de faturamento para seu projeto, crie uma.
- Acesse a página "APIs ativadas" da biblioteca de APIs no Console de APIs e selecione uma API da lista.
- Para visualizar e alterar configurações relacionadas a cotas, selecione Cotas. Para ver as estatísticas de uso, selecione Uso.
Solicitações em lote
O uso de lotes é recomendado, mas tamanhos maiores podem acionar a limitação de taxa. Não é recomendável enviar lotes maiores que 50 solicitações. Para informações sobre como fazer solicitações em lote, consulte Solicitações em lote.