Request Response Standard¶

Purpose¶

The Request Response Standard defines common request metadata, response envelopes, validation errors, and correlation behavior for future Algosure API contracts.

Request Context¶

Context	Standard
Authorization	`Authorization: Bearer <access-token>` for user and service JWTs where applicable.
Correlation	`X-Correlation-Id` is required for workflow, integration, AIOS, and material command requests.
Causation	`X-Causation-Id` is used when the request follows another command, event, or integration callback.
Tenant	Tenant context is required for tenant-scoped APIs.
Organization	OrganizationId is required for organization-scoped resources.
Idempotency	`Idempotency-Key` is required for retryable unsafe commands.

Standard Success Envelope¶

{
  "data": {},
  "meta": {
    "correlationId": "cor_123",
    "tenantId": "tenant_123",
    "organizationId": "org_123",
    "apiVersion": "v1"
  },
  "links": {}
}

Standard Error Envelope¶

{
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "Request validation failed.",
    "detail": "One or more fields are invalid.",
    "correlationId": "cor_123",
    "retryable": false,
    "fields": []
  }
}

Validation Error Field¶

Field	Meaning
`field`	Contract field path.
`code`	Stable field error code.
`message`	Safe human-readable message.
`rejectedValue`	Optional redacted value where safe.

Rules¶

Responses must include correlation metadata where a correlation ID is present or created.
TenantId and OrganizationId are included only where safe and applicable.
Errors must never expose stack traces, SQL, provider secrets, token contents, internal class names, or raw policy internals.
Empty successful command responses may return data: null plus metadata.
Collection responses use the same envelope and include pagination metadata.

Response Flow¶

flowchart LR
    Request[Request]
    Validate[Validate and authorize]
    Execute[Application service]
    Envelope[Standard envelope]
    Client[Client]

    Request --> Validate --> Execute --> Envelope --> Client