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

# Orkeia Response Pattern

> Definition of the response format adopted by Orkeia in all APIs.

# 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

```json theme={null}
{
  "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

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

### Client Error (400)

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

### Server Error (500)

```json theme={null}
{
  "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.