Nota del autor: la documentación de consulta de Request ID de APIYI se ha actualizado. Este artículo explica con claridad qué cadena copiar cuando se produce un error, qué IDs no se pueden usar, cómo guardar el task_id de un video asíncrono y qué materiales adicionales aportar cuando el registro no aparece en los logs.
Cuando una invocación falla y se abre un ticket, los desarrolladores suelen atascarse en el mismo punto: tienen una cadena de ID en la mano, pero el equipo de soporte no la encuentra en los logs. La causa habitual es haber copiado el X-Request-Id del proveedor upstream original, en lugar del X-Shellapi-Request-Id propio de APIYI. La nueva versión de la documentación se reescribió precisamente para resolver este problema; la dirección es docs.apiyi.com/faq/request-id-troubleshooting.
No se trata de un simple lavado de cara de la documentación. La versión anterior empezaba por los «encabezados de respuesta», estaba llena de «normalmente» y «puede que», y al terminar seguías sin saber dónde copiar. La nueva invierte el orden: primero da la respuesta, luego explica cómo obtenerla y, por último, ofrece una plantilla para el ticket.
Valor principal: después de leer este artículo, podrás obtener el Request ID correcto en 10 segundos y reconocer qué IDs son incorrectos. Cuando no encuentres el registro en los logs, también sabrás qué materiales adicionales aportar.

Qué cambió en la actualización de la documentación del Request ID de APIYI
La primera frase de la nueva versión del documento ya da la respuesta: el Request ID de APIYI es el encabezado de respuesta X-Shellapi-Request-Id, y cuando ocurre un error, el mensaje de error también incluye ese mismo valor al final. En la página anterior había varios sitios que trataban x-request-id como «anótalo para facilitar el diagnóstico», y de paso también los corregimos en esta actualización.
| Elemento de información | Detalles |
|---|---|
| Fecha de actualización | 2026-11-16 |
| Ubicación del documento | Nueva página de la sección FAQ «Diagnóstico mediante Request ID» |
| Respuesta clave | Request ID = encabezado de respuesta X-Shellapi-Request-Id; el (request id: ...) al final del mensaje de error es el mismo valor |
| Contenido nuevo | 2 formas de obtenerlo, tabla de comparación de ID, los logs de la consola no muestran el ID, explicación del video asíncrono, qué hacer si no lo encuentras, plantilla de ticket |
| Nota de seguridad | El Request ID no es una clave, se puede pegar en tickets, chats y capturas de pantalla; lo que no se debe compartir fuera es la clave API completa que empieza por sk- |
| A quién afecta | Todos los desarrolladores que invocan interfaces de texto, imagen, Embedding, Claude Messages, Responses y video asíncrono en APIYI |
Según el texto original del documento, el nombre de este encabezado de respuesta no distingue entre mayúsculas y minúsculas. Se devuelve tanto en las peticiones exitosas como en los errores de negocio y en las peticiones en streaming; en las peticiones en streaming, el encabezado de respuesta llega antes del primer bloque de datos. Las interfaces de video asíncrono también lo devuelven tanto en el envío como en la consulta.
Request ID de APIYI: qué cadena copiar ahora (dos rutas)
Primero, identifica el formato: el Request ID de APIYI empieza con una marca de tiempo UTC de 14 dígitos. Por ejemplo, en 2026111602224568279882196e93ae3kTS58ypN, los primeros 14 dígitos 20261116022245 corresponden a 2026-11-16 02:22:45 UTC, es decir, 10:22:45 en hora de Beijing. Compara ese prefijo con la hora de tu propia llamada y, con eso, casi siempre sabrás si copiaste la cadena equivocada.

Ruta 1: copiar directamente del JSON de error
Esta ruta es la que más conviene a la mayoría de usuarios de clientes. Cuando hay un error, el campo message del JSON de error lleva al final un fragmento (request id: ...); basta con copiar completo lo que está dentro de los paréntesis.
- Localiza el JSON de error completo en el cliente o en la salida de logs.
- Ve al final del campo
message. - Copia toda la cadena que viene después de
request id:, sin cortarla.
Registros de la consola: confirman la invocación, pero no muestran el ID de solicitud
Mucha gente, lo primero que hace, es ir a la página de “Registros” de la consola para buscar el ID. La documentación más reciente dedica una sección específica a esto: la página de registros no muestra X-Shellapi-Request-Id ni ofrece un buscador por ese campo.
En los registros puedes ver la hora, el modelo, el nombre del token, si la llamada fue streaming o no, la duración, el estado, los tokens de entrada/salida, el costo, el grupo, el multiplicador y la IP. Con eso basta para confirmar si esta invocación llegó a APIYI, qué modelo se usó y cuánto se cobró, pero no sirve para localizar la incidencia al reportarla.
Por eso, al reportar una incidencia, el ID solo puede salir de dos sitios: el texto original del error (ruta 1) y los encabezados de respuesta (ruta 2). Los registros sirven para completar datos como la hora, el modelo, el token y el costo.
Ruta 2: leer los encabezados de respuesta en el código
Si quieres automatizar la recopilación de errores, conviene registrar este encabezado directamente en el código. En todos los casos, la URL base debe ser https://api.apiyi.com/v1.
- cURL: añade
curl -D headers.txtpara escribir los encabezados de respuesta en un archivo y luego buscax-shellapi-request-iddentro del archivo. Para una revisión puntual, también puedes usarcurl -ipara imprimirlos directamente. - Python requests: después de obtener el objeto de respuesta, lee
r.headers.get("x-shellapi-request-id"). Puedes leerlo tanto cuando la llamada sale bien como cuando falla. - OpenAI SDK (Python): en el valor de retorno normal,
_request_idleex-request-id, que en APIYI normalmente está vacío. La forma correcta es usarclient.chat.completions.with_raw_response.create(...), leerraw.headers.get("x-shellapi-request-id")y luego obtener el resultado conraw.parse(). Si hay un error, leee.response.headersdentro deexcept openai.APIStatusError as e. - Node.js: con fetch, lee
res.headers.get("x-shellapi-request-id"). - Postman: después de enviar la solicitud, abre la pestaña Headers en el área de respuesta y busca
X-Shellapi-Request-Id. - Frontend en el navegador: las llamadas entre dominios están sujetas a CORS, así que JS no puede leer este encabezado. Puedes registrarlo en un proxy del backend, o consultarlo en las herramientas de desarrollador, en Network → esa solicitud → Response Headers.
🚀 Inicio rápido: para confirmar que tu código puede leer este encabezado, puedes enviar una solicitud mínima con un token de APIYI (apiyi.com) y comprobar si imprime un ID que empiece con una marca de tiempo de 14 dígitos. Este paso consumirá unos pocos tokens, así que conviene elegir una indicación con una salida muy corta.
Qué IDs no son el Request ID de APIYI
En una misma respuesta pueden aparecer varios “ID” a la vez, y muchos tickets de soporte se atascan justo en este punto. La nueva documentación incluye una tabla comparativa; aquí tienes los puntos clave.

| Campo | Origen | ¿Sirve para reportar incidencias y consultar logs? | Características identificativas |
|---|---|---|---|
| X-Shellapi-Request-Id | APIYI | ✅ Es este | Empieza por una marca de tiempo UTC de 14 dígitos |
| X-Oneapi-Request-Id | Capa intermedia | ❌ | Nombre de encabezado diferente |
| X-Request-Id | Proveedor upstream original | ❌ No se encuentra en los logs de APIYI | Suele empezar por req_ o ser un UUID |
| Encabezados personalizados de otros canales | Canal | ❌ | Nombres de encabezado variables |
id del cuerpo de respuesta |
Completion ID / Response ID | ❌ | Empieza por chatcmpl- o resp_ |
generation_id de la imagen |
Resultado de generación de imágenes | ❌ | Está en el cuerpo de la respuesta |
task_id |
Tarea asíncrona | ❌ No es el Request ID, pero debe proporcionarse junto con él | Consultar tareas y cargos |
La regla para identificarlo es sencilla: si no empieza por una marca de tiempo de 14 dígitos, no es el Request ID de APIYI. Si el ID que recibes empieza por req_, es posible que la solicitud haya llegado directamente a OpenAI oficial. En ese caso, comprueba primero si la Base URL está escrita como https://api.apiyi.com/v1.
Cómo almacenar por separado el task_id y el Request ID de los videos asíncronos
Los videos asíncronos tienen dos pasos: «enviar» y «consultar». Cada paso devuelve un nuevo X-Shellapi-Request-Id, y además hay un ID de tarea, así que es fácil confundirlos. La recomendación de la documentación nueva es: guardar por separado el Request ID del envío y el ID de tarea usado para el sondeo (polling).
| Modelo | Ubicación del ID de tarea | Interfaz de consulta | Campos propensos a confusión |
|---|---|---|---|
| Seedance | id en el nivel superior del cuerpo de la respuesta (el campo no se llama task_id) |
GET /seedance/api/v3/contents/generations/tasks/{id} |
— |
| Wan / HappyHorse | output.task_id |
GET /v1/tasks/{task_id} |
El request_id del cuerpo de la respuesta es del proveedor upstream, no el que aparece en los logs de APIYI |
A la hora de almacenar, se recomienda guardar 3 campos por tarea: el X-Shellapi-Request-Id del envío, el ID de tarea y la hora del envío. El Request ID devuelto al consultar la tarea se puede registrar según necesidad. Si falla el envío, usa el Request ID para reportar el problema; si la tarea se queda colgada o tienes dudas sobre el cobro, tanto la consulta de la tarea como la consulta del cobro necesitan el ID de tarea.
Qué añadir cuando el Request ID no aparece en los logs
Aunque tengas el ID, no siempre aparecerá en los logs. La nueva versión de la documentación dedica una sección aparte a «no hay Request ID en los logs de la consola», y los otros casos en los que no se encuentra se pueden tratar con la siguiente tabla.
| Caso | Causa | Qué añadir |
|---|---|---|
| La solicitud falla antes de recibir una respuesta | DNS, TCP/TLS, rechazo del proxy, timeout del cliente; simplemente no hay cabeceras de respuesta | Texto original del error, hora de la llamada y descripción del entorno de red |
| El cliente solo muestra «solicitud fallida» | El cliente no expone el error original | Obtén el ID por la ruta 1 o la ruta 2; los logs solo permiten confirmar si la llamada llegó |
El ID empieza por req_ |
Es posible que se haya llamado a OpenAI directamente | Revisa la Base URL y vuelve a intentarlo |
| Tampoco se encuentra en los logs | Se superó el periodo de retención o el ID no es el correcto | Verifica el formato del ID; los logs solo se conservan del mes actual y de los dos meses calendario anteriores |
Otro detalle: la página de la consola no muestra el ID, pero la API de consulta de logs permite buscar por request_id. La siguiente tabla recoge una comprobación de llamadas reales del 2026-11-16, con los modelos deepseek-flash y gpt-image-2, enviadas a https://api.apiyi.com/v1.
| Llamada | Estado HTTP | Cabeceras de respuesta | Resultado de la consulta por request_id en los logs |
|---|---|---|---|
| deepseek-flash sin streaming | 200 | Incluye x-shellapi-request-id, no incluye x-request-id | Devuelve exactamente 1 registro de consumo |
| deepseek-flash con streaming | 200 | Sí; se puede leer antes del primer bloque data: |
— |
| gpt-image-2, size=999×999 | 400 | Tiene el mismo valor que el request id al final de message | 3 líneas de error/reintento, sin línea de consumo |
| Nombre de modelo inexistente | 503 | Tiene el mismo valor que el request id al final de message | No se encuentra ni una sola línea |
La conclusión es que la página de logs de la consola no muestra el Request ID, pero la API de consulta de logs puede encontrar por request_id tanto «líneas de consumo» como «líneas de error», y no hay garantía de que existan siempre. Si la solicitud ya llegó al canal y falló en el lado del canal (por ejemplo, por un parámetro incorrecto), dejará una línea de error. Si fue rechazada en el acto en la capa de gateway (por ejemplo, porque no hay canales disponibles), puede que no haya ni una sola línea. Cuando no lo encuentres, completa el material con el ID de las cabeceras de respuesta o del texto original del error, junto con la hora de la llamada.
Si el equipo de soporte necesita reproducir el problema, puedes volver a hacer la llamada en APIYI apiyi.com con el mismo token y el mismo conjunto de parámetros, o cambiar de modelo para comprobar si aparece el mismo error. La reproducción también consume tokens, así que recuerda registrar el Request ID de cada reproducción junto con los demás datos.
🎯 Recomendación de diagnóstico: al reproducir el error, fija la Base URL en
https://api.apiyi.com/v1y registra siempre X-Shellapi-Request-Id y la hora de la llamada. Después, pasa el ID y la hora al equipo de soporte para que el backend consulte por ID; así se podrá confirmar más rápido si el error ocurrió en la capa de gateway o en la capa del canal.
Plantilla de ticket de error de Request ID de APIYI
Copia estos campos directamente en el ticket y complétalos:
- Request ID: la cadena que empieza con la marca de tiempo de 14 dígitos
- Modelo: p. ej., gpt-image-2
- Endpoint: p. ej., POST /v1/chat/completions
- Hora: con zona horaria, p. ej., 2026-11-16 11:24:04 UTC+8
- Estado HTTP: p. ej., 400 / 503
- Mensaje de error: pega el error completo, incluido
(request id: ...) - Acciones intentadas: p. ej., ya cambié de modelo, ya verifiqué la Base URL, ya reintenté 2 veces
- task_id (solo para video asíncrono): el ID de tarea que devuelve el envío
Dos advertencias: no envíes la clave API completa; si el cuerpo de la solicitud o las imágenes contienen datos privados, enmascáralos antes de enviar.
Impacto de la actualización de la documentación de Request ID para los desarrolladores
Impacto para los desarrolladores
- Menos idas y venidas al reportar un fallo: das el ID correcto desde la primera vez y el equipo de soporte no tiene que volver a preguntarte.
- Los usuarios del SDK ya no reciben valores vacíos: se aclararon la trampa de
_request_idy la forma de obtenerlo conwith_raw_response. - Las tareas de video se pueden rastrear: Request ID y ID de tarea se guardan por separado, así tienes base para consultar la tarea y el cobro.
Ten en cuenta al consultar la documentación antigua
En algunas páginas de funcionalidades por endpoint, páginas de noticias y páginas con registros de errores, todavía se describe x-request-id como «registra esto para facilitar la resolución de problemas». Si te encuentras con ese tipo de afirmación, toma como referencia esta página de la nueva versión de Request ID. También sustituye x-request-id por x-shellapi-request-id en las plantillas de código.
Preguntas frecuentes (FAQ)
P1: ¿Cuál es exactamente el Request ID de APIYI?
Es el X-Shellapi-Request-Id de los encabezados de respuesta, que comienza con una marca de tiempo UTC de 14 dígitos. Cuando se produce un error, el valor que aparece al final del mensaje de error, dentro de `(request id: …)`, es el mismo.
P2: ¿Es seguro compartir el Request ID con otras personas?
Sí, es seguro. Según la documentación original, el Request ID no es una clave, así que se puede pegar en un ticket, en un chat o en una captura de pantalla. Lo que no se debe compartir nunca es la API Key completa, la que empieza por `sk-`.
P3: ¿Por qué el ID que lee el SDK de OpenAI aparece vacío?
El `_request_id` que usa el SDK por defecto lee x-request-id. Basta con usar `with_raw_response`, o tomar x-shellapi-request-id de los encabezados de respuesta de `APIStatusError`.
P4: ¿Cómo comprobar rápido que puedo obtener el Request ID correcto?
1. Regístrate en APIYI apiyi.com y obtén una API Key; los usuarios nuevos tienen crédito de prueba gratuito.
2. Configura la Base URL como `https://api.apiyi.com/v1` y envía una solicitud mínima.
3. Imprime x-shellapi-request-id y confirma que recibes esta cadena en cada llamada; la página de logs solo permite verificar si esa llamada llegó y si se cobró, no muestra el ID.
P5: ¿Se puede consultar un error de hace tres meses?
Normalmente no. Los logs se conservan durante el mes en curso y los dos meses naturales anteriores; para los registros más antiguos tendrás que explicarlos con el Request ID y el texto original del error que hayas guardado tú.
Puntos clave del Request ID de APIYI
- El único ID correcto: X-Shellapi-Request-Id, que empieza con la hora UTC de 14 dígitos
- Dos formas de obtenerlo: copiar el mensaje de error, o leer la cabecera de respuesta desde el código (los logs solo confirman la llamada, no muestran el ID)
- Errores comunes al tomarlo: X-Request-Id,
req_,chatcmpl-,resp_y los UUID no sirven para reportar una incidencia - Para video hay que guardar dos: el Request ID del envío y el ID de tarea, cada uno por separado
- Los logs no lo son todo: la página de la consola no muestra el ID; las peticiones rechazadas en el acto por el gateway puede que ni siquiera queden registradas, así que hay que aportar el texto original del error y la hora
- Verificación práctica: envía una petición mínima en APIYI apiyi.com y comprobarás que puedes leer esta cabecera
Resumen
La actualización de la documentación de consulta del Request ID de APIYI se reduce a tres cosas:
- La respuesta primero: el Request ID es X-Shellapi-Request-Id, y al final del mensaje de error aparece ese mismo valor.
- Exclusión de IDs incorrectos: la tabla comparativa deja claras las diferencias entre la capa intermedia, el upstream, el cuerpo de la respuesta y el ID de tarea.
- Plan para cuando no se encuentra: qué material aportar en cada uno de los cuatro casos, con una plantilla de ticket lista para usar.
Te recomiendo cambiar ya los campos de log de errores en tu código a x-shellapi-request-id. A partir de ahí, cuando surja un problema, pasa el ID junto con la hora de la llamada al servicio de atención al cliente; el backend buscará por ID y después podrás enviar el ticket con todos los materiales completos.
📚 Referencias
- Documento de diagnóstico de Request ID de APIYI (nueva versión): base factual de este artículo
- Enlace:
docs.apiyi.com/faq/request-id-troubleshooting -
Descripción: incluye dos formas de obtenerlo, explicación de los logs de consola, tabla de correspondencia de ID, explicación sobre video asíncrono y plantilla de ticket
-
¿Cuánto tiempo se conservan los logs?: descripción del periodo de retención de logs
- Enlace:
docs.apiyi.com/faq/log-retention-policy - Descripción: confirma si los registros de error todavía se pueden consultar
Autor: Equipo técnico de APIYI
Contacto técnico: puedes contactarnos desde la página principal del sitio web de APIYI apiyi.com; al enviar un ticket, incluir X-Shellapi-Request-Id puede agilizar la gestión
