Skip to main content

​
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

FieldTypeRequiredDescription
statusstringYesDefines the operation state: "OK" for success or "ERROR" for failure.
dataanyYesData returned by the operation (object, array, string, etc.).
codestringNoStandardized error code (used only when status = "ERROR").
The code field always follows standardized values:
ValueDescription
auth/forbiddenAccess denied, user does not have permission.
auth/user-not-foundUser not found in the system.
auth/user-not-has-permissionUser exists but does not have the required permission.
server/errorInternal server error.
client/mandatory-field-missingMandatory field missing in the request.
client/errorGeneric client input error.
integration/errorFailure in integration with external systems.
ai/errorError in AI model processing.
funds/not-sufficient-creditsInsufficient credits to perform the operation.
security/potential-threatAction blocked due to suspected security threat.
subscription/thresholdSubscription usage limit reached.
subscription/payment-errorIssue 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.