## HTTP conventions

| Topic | Rule |
| --- | --- |
| Base host | `https://app.beacon.pt/api` (`live`) and `https://test.beacon.pt/api` (`test`) |
| Auth | `Authorization: Bearer <beacon_session_token>` |
| Organization scope | `org=<organization_slug>` on organization-scoped routes |
| Mode | `mode=test|live`, only accepted when it matches the runtime environment |
| Content-Type | `application/json` on JSON routes |
| Stripe webhooks | `Stripe-Signature` is required on `/api/webhooks/stripe*` routes |

## Error payload shape

Errors should return a consistent payload with:

- `ok: false`: explicit failure flag.
- `error`: human-readable troubleshooting summary.
- `code`: stable category identifier.
- `nextAction`: remediation hint when the domain provides one.
- `fieldErrors`: optional per-field validation details.

## Common status codes

| Code | Meaning | Recommended action |
| --- | --- | --- |
| `400` | invalid payload or query | fix `org`, `mode`, or request body and retry |
| `401` | missing or invalid bearer token | renew the Beacon session and retry |
| `403` | caller is not eligible for the action | review `OWNER`/`ADMIN` membership in the organization |
| `409` | current domain state blocks the action | inspect pending checkout, active subscription, or operational blocker |
| `422` | domain-level semantic validation failed | correct the business input before retrying |