Pular para o conteúdo principal

​
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

CampoTipoObrigatórioDescrição
statusstringSimDefine o estado da operação: "OK" para sucesso ou "ERROR" para falha.
dataanySimDados retornados pela operação (objeto, array, string, etc).
codestringNãoCódigo de erro padronizado (usado apenas quando status = "ERROR").
O campo code sempre segue valores padronizados:
ValorDescrição
auth/forbiddenAcesso negado, usuário não tem permissão.
auth/user-not-foundUsuário não encontrado no sistema.
auth/user-not-has-permissionUsuário existe mas não possui a permissão necessária.
server/errorErro interno do servidor.
client/mandatory-field-missingCampo obrigatório ausente na requisição.
client/errorErro genérico de entrada do cliente.
integration/errorFalha em integração com sistemas externos.
ai/errorErro em processamento de modelos de IA.
funds/not-sufficient-creditsCréditos insuficientes para executar a operação.
security/potential-threatAção bloqueada por suspeita de ameaça de segurança.
subscription/thresholdLimite de uso de assinatura atingido.
subscription/payment-errorProblema 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.