Tutti gli errori seguono RFC 7807. Il body è application/problem+json con i campi type, title, status, detail, request_id e opzionalmente reason oppure errors[].
{
"type": "https://www.kernelhost.com/en/kernelhost-api/errors/payment_required",
"title": "Payment required",
"status": 402,
"detail": "The order could not be paid.",
"request_id": "01HX7Z3K8Q...",
"reason": "insufficient_credit_and_no_card"
}| HTTP | type | Significato |
|---|---|---|
| 400 | validation_failed | Validazione dell'input fallita. Vedere errors[] per il dettaglio per ogni campo. |
| 401 | auth_failed | Autenticazione non riuscita. La risposta contiene sempre reason unauthorized (oppure ip_not_allowed se la chiave è limitata ad altri indirizzi IP) e di proposito non rivela altro. Verifichi chiave, secret, orario (±300 s), nonce e firma; il supporto può risalire alla causa esatta tramite il request_id. |
| 402 | payment_required | Pagamento richiesto. Per il reason si veda sotto. |
| 403 | forbidden_scope | Permesso mancante. reason: missing_scope. |
| 404 | not_found | La risorsa non esiste o non è visibile a questa chiave (evita l'enumerazione dei tenant). |
| 409 | idempotency_conflict, order_in_progress, service_not_active | Conflitto. L'Idempotency-Key è già stata usata con un altro body o un altro endpoint (idempotency_conflict, reason in_progress finché la prima richiesta è ancora in corso), un altro ordine del suo account è ancora in elaborazione (reason order_in_progress, rispettare l'header Retry-After) oppure il servizio non si trova in uno stato che consente l'azione (service_not_active, vedere service_status). |
| 413 | payload_too_large | Body della richiesta superiore a 65.536 byte. Viene rifiutato prima dell'autenticazione. |
| 422 | unprocessable | Richiesta compresa ma non eseguibile. reason billing_cycle_not_available: il prodotto non è offerto con questo ciclo di fatturazione. reason zero_total_not_allowed: l'ordine sarebbe gratuito senza un motivo valido, come un codice promozionale. |
| 429 | rate_limited | Limite di velocità superato. Rispettare l'header Retry-After. |
| 500 | internal_error | Errore interno del server. Fornisca request_id per la correlazione con l'audit log quando contatta il supporto. |
Motivi di Payment Required (HTTP 402)
Quando l'ordine non può essere pagato, l'API restituisce HTTP 402 con un reason leggibile dalla macchina nel body JSON.
insufficient_credit_and_no_card(Credito insufficiente e nessuna carta registrata. Soluzione: ricaricare il credito o aggiungere una carta nel portale clienti.)card_declined(Carta rifiutata dalla banca o dal gateway. Soluzione: provare un'altra carta o contattare la propria banca.)credit_apply_failed(Non è stato possibile applicare il credito alla fattura. Non è stato addebitato nulla e l'ordine è stato annullato. Riprovi con una nuova Idempotency-Key o contatti il supporto.)client_not_found(Account id non trovato (in pratica non dovrebbe mai accadere, contattare il supporto).)
