Todos os erros seguem a RFC 7807. O corpo é application/problem+json com os campos type, title, status, detail, request_id e, opcionalmente, reason ou 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 | Significado |
|---|---|---|
| 400 | validation_failed | Validação de entrada falhou. Consulte errors[] para o detalhe por campo. |
| 401 | auth_failed | Autenticação falhou. reason indica o 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 exigido. reason: veja abaixo. |
| 403 | forbidden_scope | Permissão ausente. reason: missing_scope. |
| 404 | not_found | O recurso não existe ou não é visível para esta chave API (impede enumeração de tenants). |
| 409 | idempotency_conflict | Idempotency-Key já utilizado com um corpo diferente. |
| 429 | rate_limited | Limite de taxa excedido. Respeite o cabeçalho Retry-After. |
| 500 | internal_error | Erro interno do servidor. Forneça request_id para correlação com o log de auditoria ao entrar em contato com o suporte. |
Motivos de pagamento exigido (HTTP 402)
Quando o pedido não pode ser pago, a API retorna HTTP 402 com um reason legível por máquina no corpo JSON.
insufficient_credit_and_no_card(Crédito insuficiente e sem cartão cadastrado. Solução: recarregar crédito ou adicionar um cartão no portal do cliente.)card_declined(O cartão foi recusado pelo banco ou gateway. Solução: usar outro cartão ou contatar seu banco.)card_expired(Cartão expirado. Solução: adicionar um novo cartão no portal do cliente.)client_not_found(ID da conta não encontrado (praticamente nunca deve ocorrer, contate o suporte).)
