L’Invariante
Diagnostica al confine dove l’errore viene emesso — mai a monte tirando a indovinare. Ogni fallimento in Axiom-Trace ha un codice stabile e un layer che lo possiede. Il playbook è: leggi il codice, identifica il layer (auth / FSM / lock / canale), correggi la causa — mai fare retry-blast su un 4xx.
Il Contratto
La mappa dei codici errore — tutto il vocabolario del fallimento:
| HTTP | Code | Layer | Significato |
|---|---|---|---|
| 400 | ACTION_FAILED, BAD_REQUEST |
manifest | constraint/validazione — correggi la chiamata |
| 401 | AUTH_REQUIRED, AUTH_FAILED, TENANT_AMBIGUOUS |
auth | problema di credenziale — correggi la credenziale |
| 403 | ACTION_FAILED (RBAC), EDGE_CAP_EXCEEDED, SCOPE_INSUFFICIENT, EDGE_SIGNATURE_REQUIRED, LICENSE_SUSPENDED |
manifest / licenza / CORS | strutturale — non guarisce da solo |
| 409 | ACTION_FAILED (FSM), PIN_AMBIGUOUS, IDEMPOTENCY_IN_PROGRESS |
FSM / auth / idempotenza | stato o ambiguità — refresh e retry |
| 413 | BATCH_TOO_LARGE |
sync | >1000 eventi — spezza |
| 429 | RATE_LIMITED |
rate limit | rispetta Retry-After |
| 503 | DRAINING, NO_ENGINE, STRIPE_NOT_CONFIGURED |
lifecycle / config | attendi o configura |
Il Flusso
Ordine di triage — il check più economico per primo:
1. leggi `code` nel body della risposta (mai solo lo status)
2. auth? → TTL sessione / ruolo / scope
3. contratto? → stato FSM, regole constraint, campi payload obbligatori
4. canale? → profondità outbox lato edge, ack ingest, last_poll_at
5. fisico? → log container, disco, salute postgresWalkthrough fail-closed — il report “bloccato” più comune:
ACCEPT_LOT → 400 ACTION_FAILED (peso_coerente)
→ il delta peso è fuori da ±0.5% — il constraint sta facendo il suo lavoro
→ REJECT_LOT il lotto (ruolo MAGAZZINIERE) o correggi il payload — mai bypassareEsempio di Payload
# Heartbeat dell'edge + salute sync, dal cloud
curl -s https://cp.axiom-trace.eu/api/v1/tenant/usage -H "Authorization: Bearer $PS" \
| jq '{edges: [.edges[] | {node_id, last_poll_at}]}'
# Lato edge: l'outbox sta drenando?
curl -s http://edge:8291/api/v1/outbox -H "Authorization: Bearer $TOKEN" | jq .
docker logs axiom-edge --tail 50I Fallimenti Noti
| Report | Causa più probabile → prima azione |
|---|---|
| “La dashboard non mostra nulla” | Edge offline o outbox arretrata → last_poll_at, log container |
| “Fatti duplicati” | Idempotency key rigenerata a ogni retry → correggi il client; la dedup su id evento ti ha già salvato |
| “Azione rifiutata che doveva passare” | Una pre_commit_rule o transizione FSM — leggi il messaggio, nomina la regola |
| “Notifiche mute” | AXIOM_CP_MAIL_MODE=log o outbox arretrata → GET /admin/notifications, log worker |
| “Tutto 401 insieme” | Rotazione key dopo re-claim → riprovisiona, non ritentare la key morta |