Hoox Docs

📨 Standard Response Schemas

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:

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)

{
  "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)

{
  "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)

{
  "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)

{
  "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:

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