Skip to main content

Headers & Envelope

Success envelope​

Success envelope
{
  "data": {
    "id": "crs_01J9Z9F3KX5N2RQ4P7M8YQK6T2",
    "title": "Intro to Algebra",
    "tenantId": "ten_01J9Z9F3KX5N2RQ4P7M8YQK6T2",
    "createdAt": "2026-04-17T09:42:11.000Z"
  },
  "meta": {
    "requestId": "req_01J9Z9F3KX5N2RQ4P7M8YQK6T2",
    "apiVersion": "v1.0",
    "traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01",
    "page": {
      "size": 50,
      "cursor": null,
      "nextCursor": "eyJ2IjoxLCJrIjp7fX0"
    }
  }
}

Error envelope (RFC 9457)​

RFC 9457 problem+json
{
  "error": {
    "type": "https://errors.ghasi.io/validation/field_required",
    "code": "validation.field_required",
    "title": "Missing required field",
    "status": 422,
    "detail": "Field 'email' is required.",
    "instance": "/api/v1/users",
    "errors": [
      {
        "field": "email",
        "code": "required"
      }
    ],
    "traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01",
    "requestId": "req_01J9Z9F3KX5N2RQ4P7M8YQK6T2",
    "retriable": false,
    "retryAfter": null,
    "docUrl": "https://docs.ghasi.io/errors/validation/field_required"
  }
}

Why not REST status codes alone?​

The envelope carries requestId, traceId, and pagination cursors so any production failure has a single string the user can hand to support. Status codes remain authoritative ? the envelope augments them.