corrigir erros.

A API 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 você a determinar como lidar com o erro.

O app Gmail precisa capturar e processar todos os erros encontrados ao usar a API REST. Este guia fornece instruções sobre como resolver erros específicos da API Gmail.

Resumo do código de status HTTP

Erros 400

Esses erros significam que a solicitação tem um problema, geralmente devido a um parâmetro obrigatório ausente.

badRequest

Esse erro pode ocorrer devido a um dos seguintes problemas no seu código:

• Um campo ou parâmetro obrigatório está ausente.
• Um valor fornecido ou uma combinação de campos é inválido.
• O anexo é inválido.

O exemplo JSON a seguir é uma representação 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 seu código de acordo com ele.

Erros 401

Esses erros significam que a solicitação não contém um token de acesso válido.

authError

Esse erro ocorre quando o token de acesso que você está usando expirou ou é inválido. A falta de autorização para os escopos solicitados também pode causar esse erro. O exemplo JSON a seguir é uma representação 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 a atualização do token automaticamente. Se isso falhar, direcione o usuário pelo fluxo do OAuth, conforme descrito em Saiba mais sobre autenticação e autorização.

Para mais informações sobre os limites do Gmail, consulte Limites de uso.

Erros 403

Esses erros ocorrem quando você excede um limite de uso ou o usuário não tem os privilégios corretos. Para determinar a causa, avalie o campo reason do JSON retornado. Esse erro ocorre nas seguintes situações:

• O app não pode ser usado no domínio do usuário autenticado.
• O projeto excedeu o limite diário.
• O usuário excedeu o limite de taxa.
• O projeto excedeu o limite de taxa.

Para mais informações, consulte Limites de uso.

dailyLimitExceeded

Esse erro ocorre quando o projeto atinge o limite da API. O exemplo JSON a seguir é uma representação desse erro:

{
  "error": {
    "errors": [
      {
        "domain": "usageLimits",
        "reason": "dailyLimitExceeded",
        "message": "Daily Limit Exceeded"
      }
    ],
    "code": 403,
    "message": "Daily Limit Exceeded"
  }
}

Esse erro ocorre quando o proprietário do aplicativo define um limite de cota para restringir o uso de um recurso específico. Para corrigir esse erro, aumente a cota no projeto na nuvem do Google Cloud. Para mais informações, consulte Gerenciar limites de cota.

domainPolicy

Esse erro ocorre quando a política do domínio do usuário não permite que seu app acesse o Gmail. O JSON a seguir é a representação 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, faça o seguinte:

1. Informe ao usuário que o domínio não permite que o app acesse o Gmail.
2. Oriente o usuário a entrar em contato com o administrador do domínio para pedir acesso ao app.

rateLimitExceeded

Esse erro indica que o usuário atingiu a taxa máxima de solicitações para a API Gmail. Esse limite varia de acordo com o tipo de solicitação. A amostra JSON a seguir é uma representação desse erro:

{
  "error": {
  "errors": [
    {
    "domain": "usageLimits",
    "message": "Rate Limit Exceeded",
    "reason": "rateLimitExceeded",
    }
  ],
  "code": 403,
  "message": "Rate Limit Exceeded"
  }
}

Para corrigir esse erro, faça o seguinte:

• Solicite um aumento de cota.
• Use a espera exponencial para tentar de novo.

userRateLimitExceeded

Esse erro ocorre quando uma solicitação atinge o limite por usuário. O exemplo JSON a seguir é uma representação 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 use a espera exponencial para repetir a solicitação.

Erros 429

Um erro 429 "Solicitações demais" 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ção simultânea por usuário. Confira abaixo informações sobre cada limite. No entanto, cada limite pode ser resolvido tentando novamente as solicitações com falha ou dividindo o processamento em várias contas do Gmail.

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 padrão de envio de e-mails diários. Esses limites são diferentes para usuários pagantes do Google Workspace e usuários de teste do gmail.com. Para conferir esses limites, consulte Limites de envio do Gmail no Google Workspace.

Esses limites são por usuário e compartilhados por todos os clientes dele, sejam clientes de API, clientes da Web ou integrados ou MSA SMTP. Se você exceder esses limites, a API vai retornar um erro HTTP 429 "Too many requests: User-rate limit exceeded (Mail sending)" com um tempo de nova tentativa. Exceder os limites diários pode resultar nesses erros por várias horas antes que o servidor aceite a solicitação.

O pipeline de envio de e-mails é complexo. Quando o usuário excede a cota, pode haver um atraso de vários minutos antes que a API comece a retornar respostas de erro 429. Não é possível presumir 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 iguais, mas independentes do IMAP. Esses limites são compartilhados entre todos os clientes da API Gmail de um usuário.

Os usuários geralmente só encontram esses limites em situações excepcionais ou abusivas. Se você exceder esses limites, a API vai retornar um erro HTTP 429 "Too many requests: User-rate limit exceeded" com um tempo de nova tentativa. Exceder os limites diários pode resultar nesses erros por várias horas antes que o servidor aceite a solicitação.

Solicitações simultâneas

A API Gmail impõe 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 usuário e garante que nenhum cliente de API esteja sobrecarregando a caixa de e-mails de um usuário do Gmail ou o servidor de back-end dele.

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 correio do usuário do Gmail simultaneamente também pode acionar esse erro. Se você exceder esse limite, a API vai retornar um erro HTTP 429 "Too many requests: Too many concurrent requests for user".

Erros 500, 502, 503 e 504

Esses erros ocorrem quando um erro inesperado do servidor surge durante o processamento da solicitação. Vários problemas podem causar esses erros, incluindo a sobreposição do tempo de uma solicitação com outra ou uma solicitação de uma ação não compatível, como tentar atualizar as permissões de uma única página no Google Sites em vez de todo o site.

Confira abaixo uma lista de erros 5xx:

• 500 Erro de back-end
• 502: Gateway inválido
• 503 Serviço indisponível
• 504 Tempo limite do gateway

backendError

Esse erro ocorre quando um erro inesperado surge durante o processamento da solicitação. O exemplo JSON a seguir é uma representação desse erro:

{
  "error": {
  "errors": [
    {
    "domain": "global",
    "reason": "backendError",
    "message": "Backend Error",
    }
  ],
  "code": 500,
  "message": "Backend Error"
  }
}

Para corrigir esse erro, use a espera exponencial para repetir a solicitação.

Repetir solicitações com falha para resolver erros

É possível repetir periodicamente uma solicitação com falha ao longo de um período crescente 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 após dois segundos 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 processamento de solicitações em ambientes simultâneos.

Comece os períodos de nova tentativa pelo menos um segundo após o erro.

Gerenciar limites de cota

Para ver ou alterar limites de uso do projeto ou para solicitar um aumento da cota, faça o seguinte:

1. Se você ainda não tem uma conta de faturamento para seu projeto, crie uma.
2. Acesse a página "APIs ativadas" da biblioteca de APIs no Console de APIs e selecione uma API da lista.
3. Para visualizar e alterar configurações relacionadas a cotas, selecione Cotas. Para ver as estatísticas de uso, selecione Uso.

Para mais informações, consulte Ver e gerenciar cotas.

Solicitações em lote

As solicitações em lote podem melhorar o desempenho, mas tamanhos maiores podem acionar a limitação de taxa. Não envie lotes maiores que 50 solicitações. Para informações sobre como fazer solicitações em lote, consulte Solicitações em lote.

Temas relacionados

• Dicas de desempenho
• Resolver problemas de autenticação e autorização