sat/openapi.yaml: add standard 4xx/5xx error responses to all endpoints

[dmchaledev]

Problem

sat/openapi.yaml documents every happy-path response but omits standard error responses from nearly all endpoints. Developers and code generators reading the spec have no idea what error shapes to expect, which leads to fragile error handling and unhelpful generated SDK clients.

A quick audit shows 30+ endpoints are missing one or more of the following standard responses:

Code	Meaning	Affected endpoints (examples)
400	Validation error	POST /groups/, POST /templates/, POST /pages/, POST /smtp/
401	Invalid or missing API key	Nearly every endpoint
403	Insufficient permissions (role-gated)	/campaigns/, /groups/{id}, /templates/{id}, /pages/{id}
404	Resource not found	GET /campaigns/{id}, GET /groups/{id}, GET /templates/{id}, etc.
500	Internal server error	Nearly every endpoint

The existing Response schema ({message, success}) is already defined in components/schemas and is a perfect fit for these error responses — it just isn't referenced from the error entries.

Proposed Fix

Add the missing error responses to every endpoint using the shared Response schema. For example, the pattern for a typical GET endpoint:

responses:
  '200':
    description: ...  # already present
  '401':
    description: Unauthorized – invalid or missing API key
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/Response'
  '403':
    description: Forbidden – insufficient role permissions
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/Response'
  '404':
    description: Resource not found
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/Response'
  '500':
    description: Internal server error
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/Response'

A responses object can also be extracted into components/responses to avoid repetition if desired.

Endpoints to Update

All paths under paths: in sat/openapi.yaml need auditing. The highest-priority ones (most-used by integrators):

• /campaigns/ (GET, POST)
• /campaigns/{id} (GET, DELETE)
• /campaigns/{id}/results (GET)
• /campaigns/summary (GET)
• /groups/ (GET, POST)
• /groups/{id} (GET, PUT, DELETE)
• /templates/ (GET, POST)
• /templates/{id} (GET, PUT, DELETE)
• /pages/ (GET, POST)
• /pages/{id} (GET, PUT, DELETE)
• /smtp/ (GET, POST)
• /smtp/{id} (GET, PUT, DELETE)
• /webhooks/ and nested endpoints
• /reports/ endpoints
• /users/ (GET, POST)

Impact

• Client SDK generators (openapi-generator, oapi-codegen) will produce proper error types
• ReDoc interactive docs will show the error section for each operation
• Integrators copying curl examples will know exactly what to catch
• Spectral rules can then enforce error response coverage going forward