Booking API – Errori

← Booking API

Formato

Gli errori hanno il formato standard delle REST API di WordPress:

{
  "code": "Prenotazione_Risorsa_prenotata",
  "message": "La Risorsa non è disponibile per le date richieste",
  "data": { "status": 500 }
}
  • code: identificativo stabile dell'errore. Basate la logica su questo campo.
  • message: messaggio in italiano, pensato per poter essere mostrato all'utente finale.
  • data.status: lo stato HTTP della risposta. data può contenere altri campi di contesto (ad esempio i parametri inviati): ignorateli.

Attenzione ai codici HTTP

I codici HTTP delle Booking API non seguono sempre le convenzioni REST:

  • molti errori di validazione e di disponibilità (dati non validi, spazio già occupato, data nel passato...) rispondono 500, non 4xx;
  • la ricerca senza risultati risponde 200 con un errore nel corpo (vedi GET /risorse/cerca).

Regole pratiche:

  1. Se il corpo JSON contiene code, è un errore (anche con status 200): gestitelo in base a code e mostrate message all'utente.
  2. Uno status 500 con un code presente nelle tabelle sotto è un errore "di business": non ripetete la richiesta identica, chiedete all'utente di modificare i dati.
  3. Uno status 5xx senza corpo JSON o con un code sconosciuto è un errore tecnico: potete riprovare più tardi (ma vedi timeout di /prenota).

Errori comuni a tutti gli endpoint

code HTTP Causa
rest_forbidden / rest_not_logged_in 401 Credenziali mancanti o errate
rest_forbidden 403 L'utente non ha i permessi per il booking
rest_missing_callback_param 400 Manca un parametro obbligatorio (elencato in data.params)
rest_invalid_param 400 Un parametro ha un formato non valido (es. data non RFC 3339, orario_opzione sconosciuta, email non valida). Dettagli in data.params e data.details
rest_no_route 404 URL o metodo HTTP errato

Sedi

code HTTP Causa
Error_Booking_sedi_not_found 404 Nessuna sede abilitata per l'utente API
Error_Booking_sedi_forbidden 403 Utente non autenticato
Sede_non_valida 500 La sede non esiste, non è abilitata per l'utente API, non ha il booking attivo o (flusso Carnet) non è tra quelle del Carnet
Sedi_non_disponibili, Sedi_non_disponibili 1, Sedi_non_disponibili 2, Sedi_non_trovate 400 Il Carnet non è utilizzabile in nessuna sede abilitata alla vostra applicazione. Attenzione: alcuni di questi codici contengono uno spazio e un numero
Carnet_Risorse_non_trovate 500 La sede non ha spazi prenotabili online, oppure (ricerca) nessuno spazio corrisponde a tipologia e capienza
Carnet_Risorse_non_accessibili 403 Nessuno spazio della sede è accessibile a questo cliente/Carnet
Carnet_Tipi_Risorse_non_trovati 500 Nessuna tipologia della sede è compatibile con il Carnet

Carnet

code HTTP Causa
Carnet_ID_non_Valido 500 Il codice Carnet non è numerico
Carnet_non_Valido 500 Nessun Carnet con questo codice
Carnet_<STATO> (es. Carnet_CESSATO, Carnet_REVOCATO) 500 Il Carnet esiste ma non è attivo
Carnet_Valida_Cliente_ID_non_valido 500 La P.IVA/CF non corrisponde al titolare del Carnet
Carnet_tipo_spazio_non_valido 500 La tipologia di spazio richiesta non è ammessa dal Carnet (il messaggio elenca quelle ammesse)
Prenotazione_Carnet_Risorsa_tipo_non_corrispondente 500 Lo spazio scelto non è di una tipologia ammessa dal Carnet
Carnet_data_successiva_scadenza 500 La prenotazione è successiva alla scadenza del Carnet
Acquisti_residuo_inadeguato 500 Residuo insufficiente (il messaggio riporta residuo e quantità richiesta)
Acquisti_disponibilità_terminata 500 Carnet esaurito
Booking_tipo_non_corrispondente 500 L'unità di misura del Carnet non è compatibile con il listino dello spazio

Date, orari e disponibilità

code HTTP Causa
Prenotazione_data_inizio_passata 500 L'inizio è nel passato
Prenotazione_data_inizio_fine_non_valida 500 L'inizio non è precedente alla fine
Prenotazione_per_piu_giorni, Booking_addebito_per_piu_giorni 500 Inizio e fine in giorni diversi
Booking_sede_non_aperta_inizio, Booking_sede_non_aperta_fine, Normalize_sede_non_aperta, Sede_non_aperta 500 La sede è chiusa in quel giorno della settimana
Booking_sede_chiusa_tutto_giorno 500 Nessuna fascia oraria aperta in quel giorno
Booking_fascia_oraria_non_valida 500 Orario personalizzato fuori dalle fasce mattina/pomeriggio (il messaggio indica le fasce)
Booking_attraversa_pausa_pranzo 500 L'orario personalizzato attraversa la pausa pranzo
Booking_orario_continuato_non_valido 500 Orario fuori dall'apertura (sedi con orario continuato)
Booking_data_festiva 500 Giorno festivo o di chiusura straordinaria (il messaggio indica quale)
Prenotazione_Preavviso_scaduto 400 Preavviso non rispettato: il messaggio indica fino a quando si poteva prenotare
CercaRisorse_nessuna 200 Ricerca: nessuno spazio libero
CercaRisorse_non_permesse 200 Ricerca: nessuno spazio accessibile a questo cliente
CercaRisorse_accesso_negato 200 Ricerca: nessuno spazio aperto negli orari richiesti

Prenotazione

code HTTP Causa
Prenotazione_Risorsa_prenotata 500 Lo spazio è già occupato in quell'orario (anche da una prenotazione in attesa di pagamento)
Prenotazione_Risorsa_non_trovata 500 risorsa_id inesistente
Prenotazione_Risorsa_non_disponibile, Prenotazione_Risorsa_non_accetta_booking 500 Lo spazio non è prenotabile online
Prenotazione_Risorsa_non_nella_sede_richiesta 500 Lo spazio non appartiene alla sede indicata
Prenotazione_Risorsa_accesso_negato 403 Lo spazio non è accessibile a questo cliente
Carnet_Risorsa_tipo_listino_non_compilato 500 Lo spazio non ha un listino: segnalatelo a Ottomedia
Error_Carnet_Inserimento_Prenotazione 500 Errore tecnico nel salvataggio

Dati di fatturazione (flusso Stripe)

code HTTP Causa
Prenotazione_Cliente_No_piva_cf 400 Manca cliente_partita_iva o cliente_partita_iva_country
REST_check_VAT-COUNTRY-ERROR 500 cliente_partita_iva_country non valido (vedi valori ammessi)
REST_check_VAT-NUM-ERROR 500 Formato della partita IVA non valido per il paese indicato
REST_check_VAT-CF-ERROR 500 Formato del codice fiscale non valido
Prenotazione_Cliente_piva_cf_NonValidi 400 Dati fiscali non validi

Stripe

code HTTP Causa
Prenotazione_Error_Stripe_Checkout_Session 500 Errore nella creazione della sessione di pagamento. La prenotazione non è stata creata: si può riprovare
Stripe_Prenotazione_Non_Trovata 404 /stripe-verify-payment: nessuna prenotazione attiva per quella sessione (pagamento fallito, sessione scaduta o session_id errato)

Errori di configurazione

Errori come Booking_sede_orari_prenotabili_non_trovati, Normalize_orari_non_validi, Carnet_Tipo_non_trovato, Carnet_UnitàMisura_non_trovata, Carnet_SedeAttivazione_non_trovata indicano un problema di configurazione della sede, dello spazio o del Carnet su BcOk. Non dipendono dalla vostra richiesta: segnalateli a Ottomedia indicando la richiesta inviata e la risposta ricevuta.