Como diagnosticar incidentes na API da OpenAI sem expor credenciais
Um guia prático para diagnosticar falhas na API da OpenAI com sinais úteis, protegendo chaves de API, limitando permissões e planejando a rotação de credenciais.
Resumo · TL;DR
Quando uma solicitação à API da OpenAI falha, preserve evidências suficientes para identificar o problema sem registrar segredos ou conteúdo sensível. Separe as credenciais por finalidade, restrinja onde elas podem ser usadas e ensaie um procedimento de rotação antes de um incidente.
Principais pontos
- Registre os resultados das solicitações e identificadores seguros, não chaves de API, cabeçalhos de autorização nem prompts e respostas completos.
- Use credenciais distintas para responsabilidades distintas e conceda apenas as permissões necessárias à carga de trabalho.
- Trate status, categoria do erro, duração e identificadores de solicitação como sinais de diagnóstico — não como justificativa para expor o conteúdo da solicitação.
- Um plano de rotação funcional inclui substituir, implantar, verificar e revogar a credencial antiga.
Nesta página (5)
É mais fácil diagnosticar um incidente na API da OpenAI quando os logs preservam evidências operacionais sem capturar credenciais ou dados desnecessários de clientes. Comece pelo sinal da falha — como um status diferente de sucesso, um tempo limite ou uma exceção da aplicação — e depois correlacione-o com um identificador de solicitação e a implantação afetada. Mantenha a chave de API fora de ambientes nos quais código não confiável ou gerado por agentes possa acessá-la.
Crie um registro de diagnóstico seguro
Para cada tentativa de chamada à API, registre apenas o necessário para responder a quatro perguntas: quando aconteceu, qual carga de trabalho fez a solicitação, que tipo de falha ocorreu e é possível correlacionar o evento com evidências do provedor?
Um registro útil pode incluir um carimbo de data e hora, um ID de operação opaco próprio, a categoria do endpoint, o status HTTP, o tempo decorrido, o número de tentativas e um ID de solicitação do provedor, se houver. Registre a classe da exceção ou uma categoria de erro sanitizada em vez de despejar o objeto de exceção: algumas bibliotecas incluem detalhes da solicitação no texto da exceção. Mantenha prompts, respostas, cabeçalhos de autorização e corpos brutos de solicitações ou respostas fora dos logs de rotina, a menos que um processo revisado estabeleça uma necessidade específica e proteções adequadas.
O código Python a seguir é um padrão ilustrativo, não uma integração testada. A função de recuperação do segredo e o tratamento da resposta dependem da sua aplicação e do SDK. O exemplo evita deliberadamente registrar o corpo da solicitação ou a credencial.
import logging
import time
import uuid
logger = logging.getLogger(__name__)
def send_request(client, payload):
operation_id = str(uuid.uuid4())
started = time.monotonic()
try:
result = client.responses.create(**payload)
logger.info(
"openai_request_succeeded",
extra={
"operation_id": operation_id,
"elapsed_ms": round((time.monotonic() - started) * 1000),
"provider_request_id": getattr(result, "_request_id", None),
},
)
return result
except Exception as exc:
# Do not log str(exc), request headers, or payload here.
logger.error(
"openai_request_failed",
extra={
"operation_id": operation_id,
"elapsed_ms": round((time.monotonic() - started) * 1000),
"exception_type": type(exc).__name__,
},
)
raise
Antes de adotar esse padrão, confirme como seu cliente disponibiliza os IDs de solicitação e se as mensagens de exceção podem conter dados sensíveis. Aplique as mesmas regras de redação em rastreamento, relatórios de erros, logs de proxy e pacotes de suporte; sanitizar apenas os logs da aplicação não é suficiente.
Use sinais de falha para restringir as causas
Um código de status ou uma exceção é uma pista, não um diagnóstico completo. Um aumento repentino de falhas de autenticação após uma implantação pode indicar uma credencial ausente, inválida ou fornecida incorretamente. O aumento de respostas de limite de taxa pode indicar uma mudança no volume ou na simultaneidade das solicitações. Os tempos limite podem estar relacionados ao acesso à rede, à latência do serviço upstream ou a um tempo limite do cliente curto demais. Uma resposta bem-sucedida do provedor seguida por uma solicitação de usuário com falha pode, em vez disso, indicar um problema de análise na aplicação ou em um serviço downstream.
Compare a taxa de falhas e a latência antes e depois de uma implantação e divida os resultados por carga de trabalho ou ambiente. Evite agrupar dados pelo valor do segredo ou registrá-lo para “verificar” se dois sistemas compartilham uma chave. Se precisar confirmar qual credencial um serviço usa, consulte a referência no gerenciador de segredos e a configuração de implantação por um meio autorizado.
Separe e restrinja as credenciais
As orientações de segurança de sandbox da OpenAI recomendam computação isolada, ambientes separados para cargas de trabalho que não devem compartilhar dados e um projeto dedicado da OpenAI para cada aplicação ou carga de trabalho. Elas também diferenciam uma chave de API da aplicação de uma chave de ambiente executor: a segunda destina-se a conectar ambientes e não autoriza outras ações de API. As orientações enumeram permissões específicas para sessões da Agents API, inferência e gerenciamento de vaults; atribua somente as permissões necessárias à carga de trabalho. Consulte as orientações de segurança de sandbox da OpenAI.
Mantenha a chave da aplicação fora de ambientes nos quais código gerado por agentes possa acessá-la. Não incorpore chaves no código-fonte, em imagens de contêiner ou em logs. Para credenciais de terceiros, as orientações recomendam manter os segredos fora do ambiente e fornecê-los por um mecanismo confiável, como um proxy ou uma abordagem baseada em vault, quando aplicável. Um segredo injetado em um ambiente continua disponível ao código executado nele; portanto, a injeção, por si só, não o torna inacessível.
Defina um procedimento de rotação de credenciais
Documente e ensaie estas etapas antes de um incidente:
- Preparar: Identifique o responsável pela credencial, suas permissões, os serviços que a utilizam e a localização no gerenciador de segredos. Confirme quem pode criar, implantar e revogar credenciais.
- Substituir: Crie uma credencial substituta com apenas as permissões necessárias. Armazene-a no gerenciador de segredos aprovado — não em um chamado, chat ou repositório de código-fonte.
- Implantar: Atualize a carga de trabalho relevante pelo processo normal de lançamento. Se a sobreposição for permitida, mantenha a credencial antiga apenas durante o período mínimo necessário para verificação.
- Verificar: Faça uma solicitação de baixo risco e confira o sucesso, a taxa de falhas e os logs. Confirme que nenhum serviço ainda depende da credencial antiga.
- Revogar e revisar: Revogue a credencial antiga. Se houver suspeita de exposição, priorize a revogação e investigue as cargas de trabalho e os logs afetados, em vez de esperar pela data de uma rotação de rotina.
Se as solicitações falharem logo após a rotação, verifique se o serviço realmente recebeu o novo segredo, se foi reiniciado ou atualizou o acesso ao segredo e se a credencial substituta tem as permissões certas. Não resolva um erro de permissão concedendo acesso amplo sem confirmar a ação necessária.
Lista de verificação compacta para incidentes
- A falha está limitada a uma carga de trabalho, ambiente ou versão?
- O status, a latência, o número de tentativas e os identificadores seguros de solicitação revelam algum padrão?
- Os logs estão livres de cabeçalhos de autorização, chaves e conteúdo desnecessário de prompts ou respostas?
- A credencial é armazenada e fornecida por um processo aprovado de gerenciamento de segredos?
- É possível substituir e revogar a credencial sem alterar serviços não relacionados?
O objetivo não é registrar tudo. É manter evidências seguras suficientes para distinguir falhas de credenciais, tráfego, rede e aplicação — e rotacionar rapidamente uma credencial caso haja suspeita de exposição.
Perguntas frequentes
O que devo registrar quando uma solicitação à API da OpenAI falha?
Registre um carimbo de data e hora, um ID de operação opaco próprio, a categoria do endpoint, o status HTTP ou uma categoria de erro sanitizada, o tempo decorrido, o número de tentativas e um ID de solicitação do provedor, se disponível. Por padrão, não registre chaves de API, cabeçalhos de autorização nem corpos completos de solicitações e respostas.
Uma chave de API deve ficar disponível para código gerado por agentes?
Evite expor uma chave de API da aplicação a código que não precisa dela. As orientações de segurança de sandbox da OpenAI dizem para manter a chave da aplicação fora do ambiente e explicam que o código gerado por agentes pode acessar arquivos e credenciais disponíveis nesse ambiente.
Quando devo rotacionar ou revogar uma chave de API da OpenAI?
Rotacione as credenciais conforme um cronograma operacional definido e revogue-as imediatamente se houver suspeita de exposição. Um procedimento completo abrange a substituição, a implantação, a verificação e a revogação da credencial antiga.
Por que uma solicitação pode falhar após a rotação de credenciais?
A carga de trabalho pode ainda estar usando um segredo antigo ou em cache, pode não ter atualizado a configuração, ou a nova credencial pode não ter uma permissão necessária. Verifique a referência do segredo implantado e as permissões necessárias sem registrar a própria credencial.
Artigos relacionados
Guides
Proteja as chaves da API da OpenAI na triagem do suporte ao cliente
Um fluxo prático de segurança para usar a OpenAI na triagem do suporte ao cliente: proteja as chaves da API, mascare os registros, limite as permissões, alterne as credenciais e exija aprovação humana.
Guides
Proteja as chaves da API da OpenAI em um fluxo de perguntas e respostas sobre documentos
Um padrão prático de segurança para responder a perguntas sobre documentos com a OpenAI: separe credenciais, restrinja permissões, oculte dados nos logs e faça a rotação segura das chaves, preservando a atribuição das fontes.
Guides
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.
Guides
Custos da API Claude Fable 5.2: uma estimativa reproduzível para diagnóstico de incidentes
Estime os custos da API Claude Fable 5.2 para diagnóstico de incidentes com pressupostos explícitos sobre tokens, cenários de repetição e sinais de falha observáveis.