## Convenções HTTP

| Tema | Regra |
| --- | --- |
| Base host | `https://app.beacon.pt/api` (`live`) e `https://test.beacon.pt/api` (`test`) |
| Auth | `Authorization: Bearer <beacon_session_token>` |
| Contexto organizacional | `org=<organization_slug>` nas rotas por organização |
| Modo | `mode=test|live`, aceite apenas quando coincide com o ambiente |
| Content-Type | `application/json` nas rotas JSON |
| Webhooks Stripe | `Stripe-Signature` obrigatório nas rotas de ingressão Stripe |

## Estrutura de erro

Erros devem devolver payload consistente com:

- `ok: false`: falha explícita.
- `error`: resumo legível para troubleshooting.
- `code`: identificador estável da categoria de erro.
- `nextAction`: passo seguinte recomendado quando existe remediação guiada.
- `fieldErrors`: lista opcional de erros por campo em validações.

## Códigos frequentes

| Código | Significado | Ação recomendada |
| --- | --- | --- |
| `400` | payload ou query inválidos | corrigir `org`, `mode` ou body e repetir |
| `401` | token Bearer ausente ou inválido | renovar sessão Beacon e repetir |
| `403` | utilizador sem papel elegível | rever membership `OWNER`/`ADMIN` na organização |
| `409` | estado actual impede a operação | confirmar se já existe checkout pendente, subscrição activa ou bloqueio operacional |
| `422` | validação semântica devolvida pelo domínio | corrigir dados funcionais antes de repetir |