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

Campo	Tipo	Obligatorio	Descripción
status	string	Sí	Define el estado de la operación: `"OK"` para éxito o `"ERROR"` para fallo.
data	any	Sí	Datos retornados por la operación (objeto, array, string, etc).
code	string	No	Código de error estandarizado (usado solo cuando `status = "ERROR"`).

El campo code siempre sigue valores estandarizados:

Valor	Descripción
`auth/forbidden`	Acceso negado, el usuario no tiene permiso.
`auth/user-not-found`	Usuario no encontrado en el sistema.
`auth/user-not-has-permission`	El usuario existe pero no tiene el permiso necesario.
`server/error`	Error interno del servidor.
`client/mandatory-field-missing`	Campo obligatorio ausente en la solicitud.
`client/error`	Error genérico de entrada del cliente.
`integration/error`	Falla en integración con sistemas externos.
`ai/error`	Error en procesamiento de modelos de IA.
`funds/not-sufficient-credits`	Créditos insuficientes para ejecutar la operación.
`security/potential-threat`	Acción bloqueada por sospecha de amenaza de seguridad.
`subscription/threshold`	Límite de uso de suscripción alcanzado.
`subscription/payment-error`	Problema 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.

Comenzando

Conceptos Clave

Referencia de API

Patrón de Respuesta Orkeia

Patrón de Respuesta de Orkeia

Estructura General

Campos

Ejemplos

Éxito

Error del Cliente (400)

Error del Servidor (500)

Beneficios

​Patrón de Respuesta de Orkeia

​Estructura General

​Campos

​Ejemplos

​Éxito

​Error del Cliente (400)

​Error del Servidor (500)

​Beneficios

Patrón de Respuesta de Orkeia

Estructura General

Campos

Ejemplos

Éxito

Error del Cliente (400)

Error del Servidor (500)

Beneficios