A API Gmail retorna dois níveis de informações de erro:
- Códigos de erro HTTP e mensagens no cabeçalho.
- Um objeto JSON no corpo da resposta com detalhes adicionais que podem ajudar a determinar como lidar com o erro.
Os apps do Gmail detectam e processam 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 destes erros, seu código:
- Um campo ou parâmetro obrigatório não foi fornecido.
- O valor informado ou uma combinação dos campos fornecidos é inválido.
- Anexo inválido.
Veja 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 corretamente.
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 por falta de autorização para os escopos solicitados. Veja 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 gerencia automaticamente a atualização do token. Se isso falhar, direcione o usuário para o fluxo do OAuth, conforme descrito em Como autorizar seu aplicativo 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.
- Seu 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 da API de cortesia para o
projeto foi atingido. Veja 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.
- Solicitar cota adicional. Para mais informações, consulte Solicitar cota adicional.
Para mais informações sobre os limites do Gmail, consulte Limites de uso.
Resolver o erro 403: limite de taxa de usuário excedido
Um erro userRateLimitExceeded indica que o limite por usuário foi
atingido. Veja 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 repetir solicitações. Para mais 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ção da API Gmail. Esse limite varia de acordo com o tipo de solicitação.
Veja 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 repetir as solicitações com falha.
Para mais informações sobre os limites do Gmail, consulte Limites de uso.
Resolver o erro 403: o aplicativo 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 que seu app acesse o Gmail. Veja a seguir a representação JSON desse 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.
- Oriente o usuário a entrar em contato com o administrador do domínio para solicitar acesso ao app.
Resolver um erro 429: excesso de solicitações
O erro 429 "Solicitações em excesso" pode ocorrer devido a limites diários de cada usuário (incluindo limites de envio de e-mail), de largura de banda ou de solicitações simultâneas por usuário. Confira as informações sobre cada limite. No entanto, cada limite pode ser resolvido tentando repetir as solicitações com falha ou dividindo o processamento em várias contas do Gmail. Por nenhum motivo, não é possível aumentar os limites por usuário. Para mais informações sobre limites, consulte Limites de uso.
Limites de envio de e-mails
A API Gmail aplica os limites diários de envio de e-mails padrão. Esses limites diferem para usuários Google Workspace pagantes e usuários de teste do gmail.com. Para saber mais sobre esses limites, consulte Limites de envio do Gmail no Google Workspace.
Esses limites são definidos por usuário e compartilhados por todos os clientes do usuário, sejam
clientes de API, nativos/da Web ou MSA SMTP. Se esses limites forem
excedidos, o erro HTTP 429 Too Many Requests "Limite de taxa de usuário excedido"
"(envio de e-mail)" será retornado com tempo para uma nova tentativa.
Se os limites diários forem excedidos, podem ocorrer esses tipos de erros por várias horas antes de a solicitação ser aceita.
O pipeline de envio de e-mails é complexo: quando o usuário excede a cota, pode demorar alguns minutos até que a API comece a retornar respostas de erro 429. Portanto, não presuma que uma resposta 200 significa que o e-mail foi enviado com sucesso.
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 Gmail de um determinado usuário.
Esses limites costumam ser atingidos apenas em situações excepcionais ou abusivas.
Se esses limites forem excedidos, o erro HTTP 429 Too Many Requests
"Limite de taxa de usuário excedido" será retornado com tempo para uma nova tentativa.
Observe que exceder os 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 aplica um limite de solicitações simultâneas por usuário (além do limite de taxa por usuário). Esse limite é compartilhado por todos os clientes da API Gmail que acessam um determinado usuário e garante que nenhum cliente de API esteja sobrecarregando a caixa de e-mails do usuário 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 que acessam simultaneamente a caixa de e-mails do usuário do Gmail também
pode acionar esse erro. Se esse limite for excedido, um erro HTTP 429 Too Many Requests
"Muitas solicitações simultâneas para o usuário" será retornado.
Resolver um erro 500: erro de back-end
Uma backendError ocorre quando surge um erro inesperado 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 repetir as solicitações com falha. Veja a seguir uma lista de erros 500:
- 502 Bad Gateway
- 503 Service Unavailable
- 504 Gateway Timeout
Repetir solicitações com falha para resolver erros
É possível repetir periodicamente uma solicitação com falha durante um período crescente para lidar com erros relacionados a limites de taxa, volume de rede ou tempo de resposta. Por exemplo, você pode repetir uma solicitação com falha após um segundo, depois após dois e depois após 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 períodos de repetição pelo menos um segundo após o erro.
Acessar ou alterar limites de uso, aumentar cota
Para conferir ou mudar os limites de uso do projeto ou solicitar um aumento da cota, siga estas etapas:
- Se você ainda não tem uma conta de faturamento para o projeto, crie uma.
- Acesse a página "APIs ativadas" da biblioteca de APIs no Console de APIs e selecione uma API da lista.
- Para ver e mudar configurações relacionadas a cotas, selecione Cotas. Para ver as estatísticas de uso, selecione Uso.
Solicitações em lote
É recomendável usar lotes, no entanto, tamanhos de lote maiores provavelmente acionarão a limitação de taxa. O envio de lotes com mais de 50 solicitações não é recomendado. Para informações sobre como fazer solicitações em lote, consulte Solicitações em lote.