All errors follow RFC 7807. Body is application/problem+json with fields type, title, status, detail, request_id and optionally reason or 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 | Meaning |
|---|---|---|
| 400 | validation_failed | Input validation failed. See errors[] for per-field detail. |
| 401 | auth_failed | Authentication failed. The response always carries reason unauthorized (or ip_not_allowed if the key is restricted to other IP addresses) and deliberately reveals nothing more. Check key, secret, clock (±300 s), nonce and signature; support can look up the exact cause by request_id. |
| 402 | payment_required | Payment required. reason see below. |
| 403 | forbidden_scope | Permission missing. reason: missing_scope. |
| 404 | not_found | Resource does not exist or is not visible to this key (prevents tenant enumeration). |
| 409 | idempotency_conflict, order_in_progress, service_not_active | Conflict. The Idempotency-Key was already used with a different body or endpoint (idempotency_conflict, reason in_progress while the first request is still running), another order of your account is still being processed (reason order_in_progress, honor Retry-After), or the service is not in a state that allows the action (service_not_active, see service_status). |
| 413 | payload_too_large | Request body larger than 65,536 bytes. It is rejected before authentication. |
| 422 | unprocessable | Understood but not executable. reason billing_cycle_not_available: the product is not offered in this billing cycle. reason zero_total_not_allowed: the order would be free without a valid reason such as a promo code. |
| 429 | rate_limited | Rate limit exceeded. Honor the Retry-After header. |
| 500 | internal_error | Internal server error. Provide request_id for correlation with the audit log when contacting support. |
Payment-required reasons (HTTP 402)
When the order cannot be paid, the API returns HTTP 402 with a machine-readable reason in the JSON body.
insufficient_credit_and_no_card(Credit insufficient and no card on file. Solution: top up credit or add a card in the customer portal.)card_declined(Card was declined by the bank/gateway. Solution: try a different card or contact your bank.)credit_apply_failed(Credit could not be applied to the invoice. Nothing was charged and the order was cancelled. Retry with a new Idempotency-Key or contact support.)client_not_found(Account id not found (should practically never happen, contact support).)
