Codici di erroreDEV

Formato delle risposte di errore e codici HTTP più comuni.

L'API V1 di MenuFacile ritorna sempre JSON sugli endpoint applicativi e segue un envelope uniforme sia in caso di successo sia in caso di errore. Il dominio del tenant inesistente è l'unico caso che restituisce HTML (la 404 brandizzata della landing).

Envelope di successo#

{
  "success": true,
  "data": { ... },
  "meta": {
    "generated_at": "2026-05-15T11:42:18+00:00",
    "locale": "it"
  }
}

• success — sempre true quando lo status HTTP è 2xx
• data — il payload (oggetto, array, o null per response vuote semantiche)
• meta — sempre presente. Contiene almeno generated_at (ISO 8601). Endpoint specifici aggiungono campi (es. locale per /menu; total, page, per_page, last_page per /items)

Envelope di errore#

{
  "success": false,
  "message": "Risorsa non trovata.",
  "errors": {
    "name": ["Il campo nome è obbligatorio."]
  }
}

• success — sempre false quando lo status HTTP è 4xx o 5xx
• message — descrizione human-readable dell'errore (localizzata IT/EN secondo l'header Accept-Language)
• errors — presente solo per errori di validazione (HTTP 422), mappa campo → [messaggi]

Codici HTTP#

Esempi pratici#

401 — Token mancante su endpoint admin#

curl https://ducatarocco.menufacile.it/api/v1/admin/items

{ "success": false, "message": "Unauthenticated." }

Fix: aggiungi header Authorization: Bearer <token>.

403 — Scope insufficiente#

curl -X POST -H "Authorization: Bearer <token-menu-read>" \
     https://ducatarocco.menufacile.it/api/v1/admin/categories

{ "success": false, "message": "Invalid ability provided." }

Fix: rigenera il token spuntando lo scope menu:write (o analytics:read per gli endpoint analytics).

404 — Tenant inesistente#

curl https://nonesisto.menufacile.it/api/v1/menu/it

Questo caso restituisce la landing 404 brandizzata del prodotto (HTML), non JSON. Verifica che il subdomain sia attivo (chiedi al cliente o al supporto).

404 — Risorsa cancellata#

curl https://ducatarocco.menufacile.it/api/v1/items/9999

{ "success": false, "message": "Resource not found." }

Fix: l'ID 9999 non esiste o è stato cancellato. Lista gli item disponibili con GET /api/v1/items.

422 — Validazione fallita#

curl -X POST -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     https://ducatarocco.menufacile.it/api/v1/admin/items \
     -d '{"price": -5}'

{
  "success": false,
  "message": "Il campo category id è obbligatorio. (and 3 more errors)",
  "errors": {
    "category_id": ["Il campo category id è obbligatorio."],
    "name": ["Il campo name è obbligatorio."],
    "name.it": ["Il campo name.it è obbligatorio."],
    "price": ["Il campo price deve essere almeno 0."]
  }
}

Fix: leggi errors, correggi i campi e ritenta. Le chiavi annidate (name.it) sono campi tradotti.

Best practice client#

• Verifica sempre success prima di leggere data: è più robusto che testare lo status HTTP per ogni 2xx.
• Fai retry solo su 5xx e 429, mai su 4xx (errori client: il retry non li risolve).
• Logga success, message e status HTTP nei tuoi sistemi: aiuta a diagnosticare.
• Non parsare il message per logica condizionale (è human-readable, può cambiare). Usa lo status HTTP e errors.

Hai bisogno di aiuto?#

Scrivi a info@menufacile.it allegando: URL chiamato, status HTTP ricevuto, body della response, ora approssimativa.