Saltar al contenido principal

​
Patrón de Respuesta de Orkeia

En Orkeia, todas las APIs siguen un patrón unificado de respuesta.
Este patrón fue definido para simplificar la integración, facilitar el manejo de errores y mantener consistencia entre todos los módulos (como Agents, Tools, Knowledge Bases, Squads y demás recursos).

​
Estructura General

{
  "status": "OK" | "ERROR",
  "data": object | array | string | null,
  "code": string | null
}

​
Campos

CampoTipoObligatorioDescripción
statusstringSíDefine el estado de la operación: "OK" para éxito o "ERROR" para fallo.
dataanySíDatos retornados por la operación (objeto, array, string, etc).
codestringNoCódigo de error estandarizado (usado solo cuando status = "ERROR").
El campo code siempre sigue valores estandarizados:
ValorDescripción
auth/forbiddenAcceso negado, el usuario no tiene permiso.
auth/user-not-foundUsuario no encontrado en el sistema.
auth/user-not-has-permissionEl usuario existe pero no tiene el permiso necesario.
server/errorError interno del servidor.
client/mandatory-field-missingCampo obligatorio ausente en la solicitud.
client/errorError genérico de entrada del cliente.
integration/errorFalla en integración con sistemas externos.
ai/errorError en procesamiento de modelos de IA.
funds/not-sufficient-creditsCréditos insuficientes para ejecutar la operación.
security/potential-threatAcción bloqueada por sospecha de amenaza de seguridad.
subscription/thresholdLímite de uso de suscripción alcanzado.
subscription/payment-errorProblema en el pago de la suscripción.

​
Ejemplos

​
Éxito

response
{
  "status": "OK",
  "data": { "id": "TOOL_123", "name": "Mi Herramienta" },
  "code": null
}

​
Error del Cliente (400)

{
  "status": "ERROR",
  "data": null,
  "code": "client/error"
}

​
Error del Servidor (500)

{
  "status": "ERROR",
  "data": null,
  "code": "server/error"
}

​
Beneficios

  • Consistencia: todos los módulos siguen el mismo formato.
  • Claridad: el campo status indica de inmediato si la operación fue exitosa o no.
  • Manejo facilitado: los clientes pueden implementar interceptores genéricos para manejar status y code.
  • Extensibilidad: nuevos códigos de error pueden ser añadidos sin romper integraciones.