[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:

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