Fundamentos de la API
Referencia base de autenticación, headers, idempotencia y errores públicos.
reference • updated 2026-03-15
Convenciones HTTP
| Tema | Regla |
|---|---|
| Base URL | https://api.beacon.pt/v1 |
| Auth | Authorization: Bearer <access_token> |
| Content-Type | application/json |
| Idempotencia | Idempotency-Key en operaciones mutables |
Estructura de error
Los errores deben devolver payload consistente con:
code: identificador estable de categoría.message: resumen legible para troubleshooting.request_id: identificador de correlación para logs y soporte.
Códigos comunes
| Código | Significado | Acción recomendada |
|---|---|---|
400 | payload inválido | corregir schema y reintentar |
401 | credencial inválida/caducada | renovar token y reintentar |
403 | permisos insuficientes | revisar scopes y contexto de organización |
409 | conflicto idempotente | verificar si la operación ya fue aplicada |
429 | throttling | reintentar con backoff exponencial |