GuidesOneMux

Como diagnosticar com segurança erros de autenticação, limite de taxa, timeout e resposta malformada da API da OpenAI

Um guia prático e atento à privacidade para diagnosticar falhas de autenticação, limitação de solicitações, timeout e resposta malformada na API da OpenAI sem expor credenciais nem dados de usuários.

AI

Resumo · TL;DR

A forma mais segura de solucionar falhas na API da OpenAI é classificá-las antes de tentar novamente. Erros de autenticação geralmente exigem corrigir a chave, a organização, o projeto ou a configuração de IP; erros de taxa e cota exigem reduzir o ritmo das solicitações ou fazer alterações administrativas; timeouts podem ser temporários; e respostas malformadas devem ser isoladas como falhas de transporte, proxy ou análise sintática. Registre metadados de diagnóstico, não credenciais nem conteúdo bruto de usuários.

Principais pontos

  • Não tente novamente erros 401 de autenticação nem erros de cobrança ou cota como se fossem falhas temporárias de rede.
  • Para respostas 429 de limitação de solicitações e 503 de sobrecarga, respeite Retry-After quando presente e aplique backoff exponencial limitado.
  • Mantenha as chaves de API fora do código-fonte, dos logs, das mensagens de exceção e dos aplicativos no lado do cliente.
  • Trate respostas que não estejam em JSON ou falhas na análise de JSON como um problema separado de transporte ou proxy e capture apenas um diagnóstico limitado e com dados ocultados.
  • Ao encaminhar um problema persistente, informe o modelo, o código do erro, o horário, o fuso horário e detalhes sanitizados da solicitação.
Nesta página (7)

É mais fácil corrigir falhas na API da OpenAI quando você as separa em erros de configuração, erros de capacidade, falhas de rede e falhas de análise da resposta. A primeira pergunta de diagnóstico deve ser: tentar novamente tem chance de mudar o resultado?

Em geral, uma resposta 401 não vai melhorar com uma nova tentativa. Uma resposta 429 causada pela velocidade das solicitações pode melhorar se você reduzir o ritmo; já uma resposta 429 causada por créditos esgotados ou por um limite de gastos exige uma alteração na conta ou no projeto. Um timeout pode ser temporário, mas timeouts repetidos podem indicar um problema de rede, proxy ou tamanho da solicitação.

Os procedimentos abaixo usam JavaScript e conceitos da biblioteca oficial da OpenAI descritos no guia de códigos de erro da OpenAI. O código é um exemplo ilustrativo, não uma integração de produção testada.

Antes de depurar: proteja credenciais e dados de usuários

Antes de reproduzir um erro, siga estas recomendações:

  • Armazene a chave de API em um gerenciador de segredos no servidor ou em uma variável de ambiente. Nunca a inclua em código de navegador, aplicativo móvel, controle de versão ou chamado de suporte.
  • Registre o horário da solicitação, a categoria do endpoint, o identificador do modelo, o status HTTP e, quando disponível, o código estruturado do erro.
  • Não registre cabeçalhos Authorization, corpos completos de solicitações, corpos brutos de respostas nem prompts que contenham dados pessoais.
  • Se precisar de um prompt para o diagnóstico, registre uma amostra com dados ocultados ou um identificador interno estável da solicitação, em vez do texto original.
  • Limite o tamanho dos dados de diagnóstico. Um proxy pode retornar uma página de erro HTML extensa, e um erro do serviço upstream pode conter dados que você não pretendia armazenar.

Uma regra operacional útil é fazer com que os logs respondam o que falhou e onde, sem registrar o que o usuário disse nem como se autenticar.

Diagnostique primeiro as falhas de autenticação 401

Os casos 401 documentados incluem autenticação inválida, chave de API incorreta, ausência de associação à organização e endereço IP não autorizado. Um erro 403 pode indicar um país, região ou território não compatível.

Verifique estes itens, nesta ordem:

  1. Confirme que o servidor está lendo o segredo esperado e que ele não foi truncado, expirou, foi revogado ou substituído.
  2. Confirme que a solicitação está sendo enviada ao endpoint e projeto pretendidos.
  3. Se sua configuração usar um identificador de organização ou uma lista de permissões de IP, confira ambos nas configurações do projeto.
  4. Verifique se a solicitação vem de um IP de saída diferente em ambiente de desenvolvimento, contêiner ou ambiente hospedado.
  5. Remova qualquer valor de credencial dos registros de depuração antes de compartilhar os logs.

Não use novas tentativas automáticas para erros 401 ou 403. Repetir a solicitação com a mesma credencial inválida pode gerar ruído e dificultar a análise do incidente. Corrija a configuração e, então, envie uma nova solicitação.

Diferencie limitação de solicitações 429 de problemas de cota e cobrança

Nem toda resposta 429 significa “tente novamente em breve”. O guia da OpenAI distingue vários casos:

Categoria da falhaAção provávelTentar novamente automaticamente?
Limite de taxa atingidoReduza o ritmo das solicitações e siga Retry-After quando presenteSim, com limites
slow_downReduza a taxa de solicitações e aumente-a gradualmenteSim, com cautela
Saldo de créditos esgotadoAdicione créditosNão
Limite de gastos da organização ou do projetoAltere o limite aplicávelNão
Limite de uso da organizaçãoSolicite um limite aprovado mais alto ou entre em contato com o suporteNão

Um ciclo de novas tentativas deve verificar o status HTTP e o código específico do erro, em vez de tratar todas as respostas 429 da mesma forma. Defina um número máximo de tentativas, use backoff exponencial e adicione jitter para evitar que vários processos tentem novamente ao mesmo tempo. Se Retry-After estiver presente, prefira o intervalo indicado, respeitando seu próprio tempo máximo de espera.

Considere também as respostas 503. A documentação de referência identifica a sobrecarga do modelo com server_is_overloaded e recomenda respeitar Retry-After, quando presente, antes de tentar novamente. Na biblioteca Python, a sobrecarga pode ser representada por InternalServerError, enquanto respostas 429 usam RateLimitError; os manipuladores não devem presumir que a sobrecarga sempre será apresentada como 429.

Investigue timeouts e falhas de conexão

A biblioteca oficial para Python documenta APITimeoutError para solicitações que atingem o tempo limite e APIConnectionError para problemas de conexão. Alguns pontos comuns para orientar o diagnóstico são:

  • Timeout antes de receber uma resposta: verifique as configurações de timeout do cliente, as rotas de rede, os proxies, os firewalls e o tamanho da solicitação.
  • Falha de conexão: verifique o DNS, os certificados TLS, as regras do firewall de saída e a configuração do proxy.
  • Falhas repetidas no servidor: confira a página de status do serviço e guarde os horários sanitizados para o suporte.

Um timeout não prova que o servidor não processou a solicitação. Para operações em que o trabalho duplicado é relevante, projete o aplicativo para que uma nova tentativa possa ser reconciliada com segurança — por exemplo, associando a operação a um registro de solicitação próprio. Não tente resolver timeouts aumentando o tempo limite indefinidamente nem tentando de novo sem um limite.

Trate respostas malformadas sem expor conteúdo

“Resposta malformada” pode descrever problemas distintos: uma solicitação inválida que gera BadRequestError, uma resposta que não corresponde ao esquema esperado ou um proxy que retorna HTML ou dados truncados em vez de JSON. O guia da OpenAI descreve BadRequestError como uma solicitação malformada ou incompleta e recomenda verificar os parâmetros obrigatórios, a codificação, o formato e o tamanho.

Em clientes HTTP brutos ou em middleware, trate os itens abaixo como verificações separadas:

  1. Verifique o status HTTP e o Content-Type antes de analisar a resposta.
  2. Analise o JSON dentro de um bloco protegido contra falhas.
  3. Valide a presença dos campos obrigatórios antes de usá-los.
  4. Registre apenas o status, o tipo de conteúdo, o tamanho da resposta e um trecho limitado com dados ocultados, se a política permitir.
  5. Nunca inclua a chave de API, o prompt completo nem a resposta completa em uma mensagem de erro de análise.

Um exemplo ilustrativo de wrapper seria:

async function parseSafeResponse(response) {
  const contentType = response.headers.get("content-type") || "";
  const body = await response.text();

  if (!contentType.toLowerCase().includes("application/json")) {
    throw new Error(`Unexpected response type: ${contentType}; length=${body.length}`);
  }

  try {
    return JSON.parse(body);
  } catch {
    throw new Error(`Invalid JSON response; length=${body.length}`);
  }
}

Este exemplo exclui intencionalmente o corpo da mensagem de erro gerada. Em produção, adicione validação de esquema adequada ao endpoint e mantenha o payload bruto apenas por meio de um processo de diagnóstico controlado e revisado quanto à privacidade.

Padrão de tratamento de erros que respeita a privacidade

O exemplo oficial de JavaScript diferencia erros de conexão, erros de limite de taxa e erros mais abrangentes da API. Amplie essa ideia classificando os erros sem exibir segredos nem dados de usuários:

import OpenAI from "openai";

const client = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });

try {
  const response = await client.responses.create({
    model: process.env.OPENAI_MODEL,
    input: "Redacted diagnostic input"
  });

  console.log({ ok: true, hasOutput: Boolean(response.output_text) });
} catch (error) {
  const details = {
    name: error?.name,
    status: error?.status,
    code: error?.code
  };

  if (error instanceof OpenAI.AuthenticationError) {
    console.error("Authentication failed", details);
  } else if (error instanceof OpenAI.RateLimitError) {
    console.error("Rate limit or quota response", details);
  } else if (error instanceof OpenAI.APIConnectionError) {
    console.error("Connection failed", details);
  } else if (error instanceof OpenAI.APIError) {
    console.error("OpenAI API error", details);
  } else {
    console.error("Unexpected local error", { name: details.name });
  }
}

Verifique os nomes das classes e o comportamento do endpoint de acordo com a versão do SDK que você implanta. Não presuma que todos os endpoints compatíveis com provedores ofereçam suporte a todos os parâmetros do SDK ou campos de resposta.

Quando encaminhar o problema

Para falhas persistentes, o guia da OpenAI recomenda fornecer o modelo, a mensagem e o código do erro, os dados e cabeçalhos da solicitação, o horário, o fuso horário e outros detalhes relevantes. Antes, sanitize essas informações: substitua credenciais, remova cookies, oculte dados pessoais e, sempre que possível, resuma o corpo da solicitação. Nunca publique informações sensíveis em um fórum público.

A decisão prática é simples: corrija problemas de autenticação e cota; reduza o ritmo diante de limitação de solicitações e sobrecarga; verifique os limites da rede quando houver timeouts; e isole falhas de análise sem reter payloads privados.

Perguntas frequentes

Devo tentar novamente todas as respostas 429 da OpenAI?

Não. Tente novamente com cautela as respostas relacionadas à taxa de solicitações e a `slow_down`, usando backoff e `Retry-After` quando estiver presente. Não espere que novas tentativas resolvam créditos esgotados, limites de gastos ou limites de uso da organização.

Por que um erro de sobrecarga da OpenAI pode aparecer como 503 em vez de 429?

O guia de erros da OpenAI documenta a sobrecarga do modelo como um erro 503 com o código `server_is_overloaded`. Os manipuladores de erro devem verificar tanto o status quanto o código, em vez de presumir que a sobrecarga sempre será uma resposta de limite de taxa.

O que devo registrar em um erro de autenticação da OpenAI?

Registre o horário, o ambiente, a categoria do endpoint, o status e o código de erro sanitizado. Não registre a chave de API, o cabeçalho `Authorization`, o corpo completo da solicitação nem o prompt bruto do usuário.

Como diagnosticar uma resposta JSON inválida?

Confira o status HTTP e o `Content-Type` antes de analisar a resposta, capture apenas um diagnóstico limitado e com dados ocultados se a política permitir, e investigue proxies ou middleware que possam estar retornando HTML, truncando dados ou alterando a resposta.

Artigos relacionados