API essentials
Baseline reference for authentication, headers, idempotency, and public errors.
reference • updated 2026-03-15
HTTP conventions
| Topic | Rule |
|---|---|
| Base URL | https://api.beacon.pt/v1 |
| Auth | Authorization: Bearer <access_token> |
| Content-Type | application/json |
| Idempotency | Idempotency-Key for mutating operations |
Error payload shape
Errors should return a consistent payload with:
code: stable category identifier.message: human-readable troubleshooting summary.request_id: correlation identifier for logs and support.
Common status codes
| Code | Meaning | Recommended action |
|---|---|---|
400 | invalid payload | fix schema and retry |
401 | invalid/expired credential | refresh token and retry |
403 | insufficient permissions | review scopes and organization context |
409 | idempotency conflict | verify if operation already applied |
429 | throttling | retry with exponential backoff |