Cómo diagnosticar incidentes de la API de OpenAI sin exponer credenciales

Es más fácil diagnosticar un incidente de la API de OpenAI cuando los registros conservan pruebas operativas sin capturar credenciales ni datos innecesarios de clientes. Empieza por la señal del fallo —como un estado distinto de éxito, un tiempo de espera agotado o una excepción de la aplicación— y relaciónala con un identificador de solicitud y el despliegue afectado. Mantén la clave de API fuera de entornos donde pueda leerla código no confiable o generado por agentes.

Crear un registro de diagnóstico seguro

Para cada intento de llamada a la API, registra solo lo necesario para responder cuatro preguntas: ¿cuándo ocurrió?, ¿qué carga de trabajo hizo la solicitud?, ¿qué tipo de fallo se produjo? y ¿se puede correlacionar el evento con pruebas del proveedor?

Un registro útil puede incluir una marca de tiempo, un ID de operación opaco propio, la categoría del endpoint, el estado HTTP, el tiempo transcurrido, el número de reintentos y un ID de solicitud del proveedor, si se devuelve. Registra la clase de excepción o una categoría de error depurada, en lugar de volcar un objeto de excepción: algunos SDK incluyen detalles de la solicitud en el texto de la excepción. Evita incluir prompts, respuestas, encabezados de autorización y cuerpos sin procesar de solicitudes o respuestas en los registros habituales, salvo que un proceso revisado justifique una necesidad concreta y existan protecciones adecuadas.

El siguiente código Python es un ejemplo ilustrativo, no una integración probada. La función de recuperación del secreto y el manejo de la respuesta dependen de la aplicación y del SDK. Evita deliberadamente registrar el cuerpo de la solicitud o la 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 adoptar este patrón, confirma cómo expone tu cliente los ID de solicitud y si los mensajes de excepción pueden contener datos sensibles. Aplica las mismas reglas de censura en el seguimiento, los informes de errores, los registros de proxy y los paquetes de soporte; depurar solo los registros de la aplicación no basta.

Usar las señales de fallo para acotar la causa

Un código de estado o una excepción son indicios, no un diagnóstico completo. Un aumento repentino de fallos de autenticación después de un despliegue puede apuntar a una credencial ausente, no válida o suministrada de forma incorrecta. Un incremento de respuestas de límite de frecuencia puede indicar que cambiaron el volumen de solicitudes o la concurrencia. Los tiempos de espera agotados pueden deberse al acceso a la red, a la latencia del sistema ascendente o a un tiempo de espera del cliente demasiado corto. Si el proveedor responde correctamente, pero después falla la solicitud del usuario, el problema podría estar en el análisis de datos de la aplicación o en un servicio posterior.

Compara la tasa de fallos y la latencia antes y después de un despliegue, y desglosa los resultados por carga de trabajo o entorno. No agrupes por el valor del secreto ni lo registres para «comprobar» si dos sistemas comparten una clave. Si necesitas verificar qué credencial usa un servicio, consulta la referencia del gestor de secretos y la configuración del despliegue mediante una vía autorizada.

Separar y restringir las credenciales

La guía de seguridad para entornos aislados de OpenAI recomienda usar recursos de cómputo aislados, entornos separados para las cargas de trabajo que no deben compartir datos y un proyecto de OpenAI dedicado a cada aplicación o carga de trabajo. También distingue entre una clave de API de aplicación y una clave de entorno executor: esta última está pensada para conectar entornos y no autoriza otras acciones de API. La guía enumera permisos específicos para sesiones de Agents API, inferencia y administración de vaults; asigna solo los permisos que necesite la carga de trabajo. Consulta la guía de seguridad para entornos aislados de OpenAI.

Mantén la clave de aplicación fuera de los entornos donde pueda leerla el código generado por agentes. No incorpores claves en el código fuente, las imágenes de contenedor ni los registros. Para las credenciales de terceros, la guía recomienda mantener los secretos fuera del entorno y proporcionarlos mediante un mecanismo confiable, como un proxy o un enfoque basado en vault cuando corresponda. Un secreto inyectado en un entorno sigue estando disponible para el código que se ejecuta allí, así que la inyección por sí sola no impide el acceso.

Definir un procedimiento para rotar credenciales

Documenta y ensaya estos pasos antes de que ocurra un incidente:

1. Preparar: Identifica quién es responsable de la credencial, sus permisos, los servicios que la usan y su ubicación en el gestor de secretos. Confirma quién puede crear, desplegar y revocar credenciales.
2. Reemplazar: Crea una credencial de reemplazo con solo los permisos necesarios. Guárdala en el gestor de secretos aprobado, no en un ticket, un chat ni un repositorio de código fuente.
3. Desplegar: Actualiza la carga de trabajo correspondiente mediante el proceso habitual de publicación. Si se permite que ambas credenciales coexistan, conserva la antigua solo durante el tiempo mínimo necesario para la verificación.
4. Verificar: Haz una solicitud de bajo riesgo y comprueba que funcione, la tasa de fallos y los registros. Confirma que ningún servicio siga dependiendo de la credencial antigua.
5. Revocar y revisar: Revoca la credencial antigua. Si sospechas que quedó expuesta, prioriza su revocación e investiga las cargas de trabajo y los registros afectados, en lugar de esperar a la fecha habitual de rotación.

Si las solicitudes fallan justo después de la rotación, comprueba si el servicio recibió el nuevo secreto, si se reinició o actualizó el acceso a los secretos y si la credencial de reemplazo tiene los permisos adecuados. No resuelvas un error de permisos concediendo acceso amplio sin confirmar qué acción se necesita.

Lista breve de comprobación para incidentes

• ¿El fallo se limita a una carga de trabajo, un entorno o una publicación?
• ¿El estado, la latencia, el número de reintentos y los identificadores seguros de solicitud muestran algún patrón?
• ¿Están los registros libres de encabezados de autorización, claves y contenido innecesario de prompts o respuestas?
• ¿Se almacena y entrega la credencial mediante una vía aprobada de gestión de secretos?
• ¿Puedes reemplazar y revocar la credencial sin cambiar servicios no relacionados?

El objetivo no es registrarlo todo. Se trata de conservar suficientes pruebas seguras para distinguir entre fallos de credenciales, tráfico, red y aplicación, y de poder rotar rápidamente una credencial si sospechas que quedó expuesta.