> ## 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.

# Padrão de Resposta Orkeia

> Definição do formato de resposta adotado pela Orkeia em todas as APIs.

# Padrão de Resposta da Orkeia

No Orkeia, todas as APIs seguem um **padrão unificado de resposta**.\
Esse padrão foi definido para simplificar a integração, facilitar o tratamento de erros e manter consistência entre todos os módulos (como *Agents*, *Tools*, *Knowledge Bases*, *Squads* e demais recursos).

## Estrutura Geral

```json theme={null}
{
  "status": "OK" | "ERROR",
  "data": object | array | string | null,
  "code": string | null
}
```

## Campos

| Campo  | Tipo   | Obrigatório | Descrição                                                                 |
| ------ | ------ | ----------- | ------------------------------------------------------------------------- |
| status | string | Sim         | Define o estado da operação: `"OK"` para sucesso ou `"ERROR"` para falha. |
| data   | any    | Sim         | Dados retornados pela operação (objeto, array, string, etc).              |
| code   | string | Não         | Código de erro padronizado (usado apenas quando `status = "ERROR"`).      |

O campo `code` sempre segue valores padronizados:

| Valor                            | Descrição                                             |
| -------------------------------- | ----------------------------------------------------- |
| `auth/forbidden`                 | Acesso negado, usuário não tem permissão.             |
| `auth/user-not-found`            | Usuário não encontrado no sistema.                    |
| `auth/user-not-has-permission`   | Usuário existe mas não possui a permissão necessária. |
| `server/error`                   | Erro interno do servidor.                             |
| `client/mandatory-field-missing` | Campo obrigatório ausente na requisição.              |
| `client/error`                   | Erro genérico de entrada do cliente.                  |
| `integration/error`              | Falha em integração com sistemas externos.            |
| `ai/error`                       | Erro em processamento de modelos de IA.               |
| `funds/not-sufficient-credits`   | Créditos insuficientes para executar a operação.      |
| `security/potential-threat`      | Ação bloqueada por suspeita de ameaça de segurança.   |
| `subscription/threshold`         | Limite de uso de assinatura atingido.                 |
| `subscription/payment-error`     | Problema no pagamento da assinatura.                  |

## Exemplos

### Sucesso

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

### Erro do Cliente (400)

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

### Erro do Servidor (500)

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

## Benefícios

* **Consistência**: todos os módulos seguem o mesmo formato.
* **Clareza**: o campo `status` já indica de imediato se a operação foi bem-sucedida ou não.
* **Tratamento facilitado**: clientes podem implementar interceptadores genéricos para lidar com `status` e `code`.
* **Extensibilidade**: novos códigos de erro podem ser adicionados sem quebrar integrações.