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

{
  "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

response

{
  "status": "OK",
  "data": { "id": "TOOL_123", "name": "Minha Ferramenta" },
  "code": null
}

Erro do Cliente (400)

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

Erro do Servidor (500)

{
  "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.

Guia Rápido

Conceitos Chave do Orkeia

Referência de API

Padrão de Resposta Orkeia

Padrão de Resposta da Orkeia

Estrutura Geral

Campos

Exemplos

Sucesso

Erro do Cliente (400)

Erro do Servidor (500)

Benefícios

​Padrão de Resposta da Orkeia

​Estrutura Geral

​Campos

​Exemplos

​Sucesso

​Erro do Cliente (400)

​Erro do Servidor (500)

​Benefícios

Padrão de Resposta da Orkeia

Estrutura Geral

Campos

Exemplos

Sucesso

Erro do Cliente (400)

Erro do Servidor (500)

Benefícios