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/reseller-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 fallita. reason indica il motivo: missing_headers, bad_key, bad_timestamp, timestamp_out_of_window, bad_nonce, bad_signature, signature_mismatch, replay_detected, unknown_or_locked_key, ip_not_allowed. |
| 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 | Idempotency-Key già utilizzata con un body differente. |
| 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.)card_expired(Carta scaduta. Soluzione: aggiungere una nuova carta nel portale clienti.)client_not_found(Account id non trovato (in pratica non dovrebbe mai accadere, contattare il supporto).)
