GuidesOneMux

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.

AI

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:

  1. 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.
  2. 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.
  3. 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.
  4. 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.
  5. 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