Unif API DocsErrores
Cada error que UnifAPI devuelve a agentes y clientes HTTP, qué significa y cómo recuperarse.
Los errores siempre vuelven en el mismo envelope, independientemente de qué operación de datos públicos se haya llamado:
{
"error": {
"type": "rate_limited",
"message": "Workspace rate limit exceeded.",
"request_id": "unif_5471f8cfa3814204a280b73df8c93167"
}
}error.typeproviene de un vocabulario cerrado (ver la tabla de abajo): estable, legible por máquina y seguro para que agentes y clientes lo discriminen.error.messagees para humanos y puede cambiar sin previo aviso.error.request_ides el id de traza de UnifAPI. Inclúyelo en las solicitudes de soporte.error.issuesestá presente solo cuandotype = validation_error: es la lista de issues de Zod en bruto.
El estado HTTP refleja el tipo: los clientes pueden elegir la señal que prefieran.
Referencia
| Estado | type | Cuándo ocurre | Recuperación |
|---|---|---|---|
| 400 | validation_error | La solicitud falló la validación del lado del gateway (consulta incorrecta, campo de cuerpo faltante). | Inspecciona error.issues. Corrige la solicitud. |
| 400 | invalid_id | El id proporcionado era sintácticamente válido pero la fuente pública no lo aceptó. | Usa un id real. |
| 401 | unauthorized | Las credenciales de OAuth o de API key faltan, están malformadas, revocadas o deshabilitadas. | Vuelve a autenticarte o rota la clave. |
| 404 | not_found | El recurso (vídeo, usuario, sala, ...) no existe, está eliminado o es privado. | Confirma el id; algunos recursos son privados y devuelven 404 por diseño. |
| 429 | rate_limited | Se excedió el límite de tasa del espacio de trabajo o de la fuente. | Respeta Retry-After. Consulta Límites de tasa. |
| 500 | internal_error | UnifAPI mismo falló (excepción no capturada). | Seguro reintentar. Reporta request_id si persiste. |
| 500 | response_shape_error | Los datos de la fuente ya no coinciden con el esquema publicado. | Reporta request_id: la deriva es un bug. |
| 502 | upstream_error | Una fuente de datos públicos devolvió un error del que UnifAPI no puede recuperarse. | Inspecciona error.message. |
| 503 | upstream_unavailable | Una fuente de datos públicos agotó el tiempo de espera o es inalcanzable. | Reintenta con backoff exponencial. |
La tabla anterior es el contrato público del vocabulario de errores actual.
Anatomía de un error de validación
Para validation_error, el array issues lleva la lista de issues de Zod en bruto para que un agente o llamante pueda mapear los errores de vuelta a los campos:
{
"error": {
"type": "validation_error",
"message": "Request validation failed.",
"issues": [
{
"code": "too_big",
"maximum": 50,
"type": "number",
"inclusive": true,
"path": ["limit"],
"message": "Number must be less than or equal to 50"
}
]
}
}Registra siempre request_id
Cada respuesta de error lleva request_id cuando UnifAPI puede adjuntar uno. Regístralo e inclúyelo en las solicitudes de soporte; es la forma más rápida de depurar una ejecución de Skill o una llamada HTTP fallida.