Tratamento de erros, limitação de taxa e gerenciamento de cotas

Ao consultar a API Developer Knowledge ou o servidor MCP do Developer Knowledge em aplicativos de produção e agentes de IA, é necessário ter tratamento de erros e gerenciamento de cotas para alcançar um alto desempenho.

Neste guia, você aprenderá a:

  • Implemente a espera exponencial truncada com instabilidade para respostas HTTP 429.
  • Processar códigos de erro canônicos do gRPC (INVALID_ARGUMENT, PERMISSION_DENIED, RESOURCE_EXHAUSTED).
  • Gerenciar tempos limite de conexão do MCP e lógica de nova tentativa.
  • Aplique as práticas recomendadas de gerenciamento de cotas e armazenamento em cache.

Limitação de taxa HTTP 429 e espera exponencial

Quando as taxas de solicitação excedem a cota padrão da API, o serviço retorna um erro HTTP 429 Too Many Requests. Os aplicativos precisam implementar a lógica de repetição usando a espera exponencial truncada com instabilidade para evitar sobrecarregar o serviço.

Espera exponencial truncada

Calcule os atrasos de novas tentativas usando a seguinte fórmula:

retry_delay = min(max_delay, initial_delay * (2 ^ attempt) + jitter)

Use os seguintes parâmetros para calcular os atrasos de novas tentativas:

  • initial_delay: atraso inicial da nova tentativa (por exemplo, 1 segundo).
  • max_delay: espera máxima (por exemplo, 32 segundos).
  • attempt: contagem atual de novas tentativas (0, 1, 2, ...).
  • jitter: valor aleatório entre 0 e 1 segundo para evitar picos de sincronização de linhas de execução (problema de efeito manada).

Tratamento de erros do gRPC

Os aplicativos que acessam o serviço pelo gRPC precisam inspecionar os valores canônicos de grpc.StatusCode.

Códigos de status padrão do gRPC

A tabela a seguir lista os códigos de status canônicos do gRPC retornados pelo serviço e o processamento recomendado do cliente:

Código de status gRPC Status HTTP Causa raiz Ação recomendada
INVALID_ARGUMENT 400 Bad Request String de consulta incorreta, formato de parâmetro inválido ou máscara de campo inválida. Não repita. Corrija os parâmetros da solicitação antes de repetir.
UNAUTHENTICATED 401 Unauthorized Chave de API ou token de acesso OAuth ausente, expirado ou malformado. Não repita. Atualize as credenciais ou gere uma chave de API válida.
PERMISSION_DENIED 403 Forbidden A chave de API não tem permissão ou a API Developer Knowledge está desativada no projeto. Não repita. Verifique se a API está ativada no console do Google Cloud.
NOT_FOUND 404 Not Found O caminho do documento parent especificado não existe. BatchGetDocuments falha de forma atômica se algum documento solicitado não for encontrado. Não repita. Verifique o nome do recurso do documento.
RESOURCE_EXHAUSTED 429 Too Many Requests O limite de taxa ou de cota do projeto foi excedido. Tente de novo usando a espera exponencial com instabilidade.
UNAVAILABLE 503 Service Unavailable Desconexão transitória da rede ou reinicialização do servidor. Tente de novo com espera exponencial.
DEADLINE_EXCEEDED 504 Gateway Timeout A solicitação excedeu o prazo de RPC configurado antes da conclusão. Tente de novo com um tempo limite de RPC do cliente maior.

Tempo limite de conexão e gerenciamento de erros do MCP

O servidor MCP de conhecimento do desenvolvedor é um serviço remoto hospedado em https://developerknowledge.googleapis.com/mcp acessado por HTTPS (usando HTTP POST ou eventos enviados pelo servidor). Os hosts e agentes de IA precisam gerenciar tempos limite de conexão e erros de ferramentas de forma adequada.

Tempos limite de execução da ferramenta

Quando um agente invoca search_documents, get_documents ou answer_query, as chamadas de função podem exceder as janelas de tempo limite (por exemplo, 30 segundos) se as conexões de rede estiverem lentas.

Para lidar com tempos limite de execução de ferramentas:

  • Configure os tempos limite do cliente: defina os tempos limite de execução da ferramenta como 30 a 60 segundos na configuração do cliente host do MCP.
  • Lidar com interrupções de rede: tente novamente as solicitações HTTP com falha usando espera exponencial quando houver quedas temporárias de rede ou respostas HTTP 503.
  • Inspecionar mensagens de erro: analise mensagens de erro JSON-RPC padrão ou códigos de status de erro HTTP para distinguir argumentos inválidos do esgotamento da cota.

Práticas recomendadas de gerenciamento de cotas

Siga estas práticas recomendadas para manter o uso ideal da API e evitar limites de taxa inesperados:

  1. Armazenar em cache o conteúdo do documento recuperado: armazene documentos Markdown buscados localmente ou em um cache (como o Redis) ao criar aplicativos que acessam as mesmas páginas com frequência.
  2. Use a recuperação em lote: use documents.batchGet em vez de executar várias solicitações documents.get sequenciais.
  3. Otimize os campos de consulta: solicite apenas os campos de resposta necessários usando máscaras de campo seletivas (fields=results(parent,content)).
  4. Monitore o consumo de cota: acompanhe as taxas de solicitação de API no painel de APIs do console do Google Cloud.

Conteúdo relacionado