Envelope

Enveloping is best except when,

1. Save extra bytes for absolutely critical performance reasons.

2. Rest purity is required.

Standard envelope format

{
  "data": { ... },            // Actual payload
  "meta": { ... },            // Pagination, request-id
  "errors": [
    {
      "code": "string",       // Stable, machine-readable error code (snake_case)
      "message": "string",    // Human-readable explanation
      "details": { ... }      // Optional structured info for debugging/UI
    }
  ]
}

Examples

{
  "data": [
    { "id": 1, "name": "Alice" },
    { "id": 2, "name": "Bob" }
  ],
  "meta": { "page": 1, "page_size": 2, "total_pages": 5 }
}

{
  "errors": [
    {
      "code": "invalid_request",
      "message": "Email is invalid",
      "details": { "field": "email" }
    }
  ]
}