> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hoox.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Standard Response Schemas

> High-integrity JSON response templates, success envelopes, edge error codes, and shared error middleware specs.

To ensure predictable error handling and parsing across all microservices, Hoox enforces a **strict response contract**. Every worker responds with a standardized JSON envelope containing tracing details, operation status, results payload, and detailed error models.

This document details the exact JSON templates, types, and error factories utilized in the monorepo.

***

## 🛡️ 1. Standard Response Envelope

Every HTTP response returned by an edge worker is encapsulated within a unified JSON envelope:

```typescript theme={null}
export interface ResponseEnvelope<T> {
  success: boolean; // Absolute state of the operation
  requestId: string; // UUIDv4 trace ID mapped from request
  result?: T; // Operation success metadata payload
  error?: {
    // Detail model present only if success = false
    code: string; // Unique machine-parseable error token
    message: string; // Human-readable error description
    details?: any; // Optional specific array of field issues
  };
}
```

***

## 🏆 2. Success Response Templates

### A. Trade Execution Fill Success (`trade-worker` - 200 OK)

```json theme={null}
{
  "success": true,
  "requestId": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
  "result": {
    "orderId": "18049284739",
    "status": "Filled",
    "executedQty": 0.005,
    "price": 68425.5,
    "timestamp": 1779261050000
  },
  "error": null
}
```

***

### B. Telegram Push Success (`telegram-worker` - 200 OK)

```json theme={null}
{
  "success": true,
  "requestId": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
  "result": {
    "messageId": 482904,
    "delivered": true
  },
  "error": null
}
```

***

## 🚨 3. Error Models & Edge Error Codes

When a worker operation fails, the `success` flag is set to `false`, the `result` field is omitted or set to `null`, and the `error` model is fully populated:

### A. 400 Bad Request (JSON Validation Error)

```json theme={null}
{
  "success": false,
  "requestId": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid JSON payload structure.",
    "details": [{ "field": "quantity", "issue": "Must be greater than zero." }]
  }
}
```

***

### B. 409 Conflict (Idempotency Mutex Intercept)

```json theme={null}
{
  "success": false,
  "requestId": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
  "error": {
    "code": "DUPLICATE_REQUEST",
    "message": "Order rejected. Durable Object locked: trace ID already processed in the last 24 hours."
  }
}
```

***

## 🛠️ 4. Shared `Errors` Factory Middleware

To enforce this response contract without writing redundant JSON wrappers in every worker, we use the standardized `Errors` factory from the shared monorepo package `@jango-blockchained/hoox-shared/errors`:

```typescript theme={null}
import { Errors } from "@jango-blockchained/hoox-shared/errors";

// 1. Validation Failures (400 Bad Request)
if (!payload.symbol) {
  return Errors.badRequest("Symbol is a required parameter.");
}

// 2. Secret Key Mismatch (401 Unauthorized)
if (requestHeaderKey !== env.INTERNAL_KEY_BINDING) {
  return Errors.unauthorized("Access Denied: Invalid X-Internal-Auth-Key.");
}

// 3. System Exceptions (500 Internal Server Error)
try {
  await database.write(data);
} catch (err: any) {
  return Errors.internal(`Database write exception: ${err.message}`);
}
```

These factory methods automatically serialize the exception, attach the active `requestId` from the context, set the correct HTTP status code, and return a compliant `Response` object.

### 🔗 Next Steps

* **[API Endpoint Directory](endpoints)** — Analyze REST routes, headers, and endpoints mappings.
* **[Request Payload Schemas](payloads)** — Check JSON request payload specifications and typescript interfaces.