> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orkeia.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Patrón de Respuesta Orkeia

> Definición del formato de respuesta adoptado por Orkeia en todas las APIs.

# 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

```json theme={null}
{
  "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

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

### Error del Cliente (400)

```json theme={null}
{
  "status": "ERROR",
  "data": null,
  "code": "client/error"
}
```

### Error del Servidor (500)

```json theme={null}
{
  "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.