## Convenciones HTTP

| Tema | Regla |
| --- | --- |
| Host base | `https://app.beacon.pt/api` (`live`) y `https://test.beacon.pt/api` (`test`) |
| Auth | `Authorization: Bearer <beacon_session_token>` |
| Alcance de organización | `org=<organization_slug>` en rutas por organización |
| Modo | `mode=test|live`, solo aceptado cuando coincide con el entorno runtime |
| Content-Type | `application/json` en rutas JSON |
| Webhooks Stripe | `Stripe-Signature` obligatorio en `/api/webhooks/stripe*` |

## Estructura de error

Los errores deben devolver un payload consistente con:

- `ok: false`: fallo explícito.
- `error`: resumen legible para troubleshooting.
- `code`: identificador estable de categoría.
- `nextAction`: siguiente paso recomendado cuando el dominio lo ofrece.
- `fieldErrors`: lista opcional de errores por campo.

## Códigos comunes

| Código | Significado | Acción recomendada |
| --- | --- | --- |
| `400` | payload o query inválidos | corregir `org`, `mode` o body y reintentar |
| `401` | bearer token ausente o inválido | renovar la sesión Beacon y reintentar |
| `403` | el usuario no es elegible para la acción | revisar membresía `OWNER`/`ADMIN` en la organización |
| `409` | el estado actual del dominio bloquea la operación | inspeccionar checkout pendiente, suscripción activa o bloqueo operativo |
| `422` | validación semántica de dominio fallida | corregir el input funcional antes de repetir |