corrigir erros.

A API Gmail retorna dois níveis de informações de erro:

  • Códigos e mensagens de erro de 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 detectar e processar todos os erros que podem ocorrer 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

Código do erro Descrição
200 - OK A solicitação foi bem-sucedida (essa é a resposta padrão para solicitações HTTP bem-sucedidas).
400 - Bad Request Não foi possível atender à solicitação devido a um erro do cliente.
401 - Unauthorized A solicitação contém credenciais inválidas.
403 - Forbidden A solicitação foi recebida e compreendida, mas o usuário não tem permissão para realizá-la.
404 - Not Found Não foi possível encontrar a página solicitada.
429 - Too Many Requests Muitas solicitações para a API.
500, 502, 503, 504 - Server Errors Ocorreu um erro inesperado ao processar a solicitação.

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 não foi fornecido.
  • O valor fornecido ou uma combinação de campos fornecidos é inválido.
  • O anexo é inválido.

O exemplo de 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 o 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 está expirado ou é inválido. Ele também pode ser causado pela falta de autorização para os escopos solicitados. O exemplo de 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:

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

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

dailyLimitExceeded

Esse erro ocorre quando o limite da API para o projeto é atingido. O exemplo de 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 aparece quando o proprietário do aplicativo define um limite de cota para limitar 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 o acesso ao Gmail pelo seu app. 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, tente o seguinte:

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

rateLimitExceeded

Esse erro indica que o usuário atingiu a taxa máxima de solicitações da API Gmail. Esse limite varia dependendo do tipo de solicitação. O exemplo de 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, tente o seguinte:

userRateLimitExceeded

Esse erro ocorre quando o limite por usuário é atingido. O exemplo de 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 tentar a solicitação novamente.

Erros 429

Um erro 429 "Too many requests" pode ocorrer devido a limites diários por usuário (incluindo limites de envio de e-mails), limites de largura de banda ou um limite de solicitação simultânea por usuário. As informações sobre cada limite são apresentadas a seguir. No entanto, cada limite pode ser resolvido tentando novamente as 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 nenhum motivo. 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 pagos do Google Workspace e usuários de 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 integrados ou da Web ou MSA SMTP. Se esses limites forem excedidos, um erro HTTP 429 "Too many requests: User-rate limit exceeded (Mail sending)" será retornado com um tempo para tentar novamente. O excesso de limites diários pode resultar nesses 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 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.

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 usuário.

Esses limites normalmente são atingidos apenas em situações excepcionais ou abusivas. Se esses limites forem excedidos, um erro HTTP 429 "Too many requests: User-rate limit exceeded" será retornado com um tempo para tentar novamente. O excesso de limites diários pode resultar nesses erros por várias horas antes que a solicitação seja aceita.

Solicitações simultâneas

A API Gmail aplica 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 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.

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 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.

Erros 500, 502, 503, 504

Esses erros ocorrem quando um erro inesperado do servidor surge ao processar a solicitação. Vários problemas podem causar esses erros, incluindo o tempo de uma solicitação que se sobrepõe a outra ou uma solicitação de uma ação não aceita, como tentar atualizar permissões para uma única página no Google Sites em vez de todo o site.

A seguir, confira uma lista de erros 5xx:

  • Erro de back-end 500
  • 502 Bad Gateway
  • 503 Service Unavailable
  • 504 Gateway Timeout

backendError

Esse erro ocorre quando um erro inesperado surge ao processar a solicitação. O exemplo de 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 tentar a solicitação novamente.

Tentar novamente solicitações com falha para resolver erros

Você pode tentar novamente uma solicitação com falha periodicamente 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 de dois segundos e, em seguida, 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.

Inicie os períodos de repetição 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

O uso de solicitações em lote é incentivado. No entanto, tamanhos de lote maiores provavelmente vão acionar a limitação de taxa. Não é recomendável enviar lotes com mais de 50 solicitações. Para informações sobre como fazer solicitações em lote, consulte Solicitações em lote.