Orkeia Response Standard

In Orkeia, all APIs follow a unified response standard.
This standard is defined to simplify integration, facilitate error handling, and maintain consistency between all modules (such as Agents, Tools, Knowledge Bases, Squads, and other resources).

General Structure

{
  "status": "OK" | "ERROR",
  "data": object | array | string | null,
  "code": string | null
}

Fields

Field	Type	Required	Description
status	string	Yes	Defines the operation state: `"OK"` for success or `"ERROR"` for failure.
data	any	Yes	Data returned by the operation (object, array, string, etc.).
code	string	No	Standardized error code (used only when `status = "ERROR"`).

The code field always follows standardized values:

Value	Description
`auth/forbidden`	Access denied, user does not have permission.
`auth/user-not-found`	User not found in the system.
`auth/user-not-has-permission`	User exists but does not have the required permission.
`server/error`	Internal server error.
`client/mandatory-field-missing`	Mandatory field missing in the request.
`client/error`	Generic client input error.
`integration/error`	Failure in integration with external systems.
`ai/error`	Error in AI model processing.
`funds/not-sufficient-credits`	Insufficient credits to perform the operation.
`security/potential-threat`	Action blocked due to suspected security threat.
`subscription/threshold`	Subscription usage limit reached.
`subscription/payment-error`	Issue with subscription payment.

Examples

Success

response

{
  "status": "OK",
  "data": { "id": "TOOL_123", "name": "My Tool" },
  "code": null
}

Client Error (400)

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

Server Error (500)

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

Benefits

Consistency: all modules follow the same format.
Clarity: the status field immediately indicates whether the operation was successful or not.
Facilitated Handling: clients can implement generic interceptors to handle status and code.
Extensibility: new error codes can be added without breaking integrations.

Getting Started

Core Concepts

API Reference

Orkeia Response Pattern

Orkeia Response Standard

General Structure

Fields

Examples

Success

Client Error (400)

Server Error (500)

Benefits

​Orkeia Response Standard

​General Structure

​Fields

​Examples

​Success

​Client Error (400)

​Server Error (500)

​Benefits

Orkeia Response Standard

General Structure

Fields

Examples

Success

Client Error (400)

Server Error (500)

Benefits