Všechny chyby se řídí RFC 7807. Tělo odpovědi je application/problem+json s poli type, title, status, detail, request_id a případně reason nebo 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 | Význam |
|---|---|---|
| 400 | validation_failed | Validace vstupu selhala. Detail pro každé pole najdete v errors[]. |
| 401 | auth_failed | Ověření selhalo. Odpověď vždy obsahuje reason unauthorized (nebo ip_not_allowed, pokud je klíč omezen na jiné IP adresy) a záměrně neprozrazuje nic dalšího. Zkontrolujte klíč, secret, čas (±300 s), nonce a podpis; podpora dohledá přesnou příčinu podle request_id. |
| 402 | payment_required | Vyžadována platba. reason viz níže. |
| 403 | forbidden_scope | Chybí oprávnění. reason: missing_scope. |
| 404 | not_found | Zdroj neexistuje nebo není pro tento klíč viditelný (brání výčtu nájemníků). |
| 409 | idempotency_conflict, order_in_progress, service_not_active | Konflikt. Buď byl Idempotency-Key již použit s jiným tělem či na jiném koncovém bodu (idempotency_conflict, reason in_progress, dokud první požadavek ještě běží), nebo se ještě zpracovává jiná objednávka Vašeho účtu (reason order_in_progress, respektujte Retry-After), nebo služba není ve stavu, který akci umožňuje (service_not_active, viz service_status). |
| 413 | payload_too_large | Tělo požadavku je větší než 65 536 bajtů. Je odmítnuto ještě před ověřením. |
| 422 | unprocessable | Požadavek je srozumitelný, ale nelze jej provést. reason billing_cycle_not_available: produkt se v tomto fakturačním cyklu nenabízí. reason zero_total_not_allowed: objednávka by byla zdarma bez platného důvodu, například slevového kódu. |
| 429 | rate_limited | Překročeno omezení rychlosti. Respektujte hlavičku Retry-After. |
| 500 | internal_error | Interní chyba serveru. Při kontaktování podpory uveďte request_id pro korelaci s auditním logem. |
Důvody Payment-Required (HTTP 402)
Pokud objednávku nelze zaplatit, API vrací HTTP 402 se strojově čitelným důvodem v těle JSON.
insufficient_credit_and_no_card(Kredit nestačí a žádná karta není uložena. Řešení: dobít kredit nebo přidat kartu v zákaznickém portálu.)card_declined(Karta byla zamítnuta bankou nebo bránou. Řešení: zkusit jinou kartu nebo kontaktovat banku.)credit_apply_failed(Kredit se nepodařilo uplatnit na fakturu. Nic nebylo strženo a objednávka byla zrušena. Zkuste to znovu s novým Idempotency-Key nebo kontaktujte podporu.)client_not_found(ID účtu nenalezeno (prakticky by se to nikdy nemělo stát, kontaktujte podporu).)
