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/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 | Significado |
|---|---|---|
| 400 | validation_failed | Validação de entrada falhou. Consulte errors[] para o detalhe por campo. |
| 401 | auth_failed | Falha na autenticação. A resposta contém sempre reason unauthorized (ou ip_not_allowed se a chave estiver restrita a outros endereços IP) e, propositadamente, não revela mais nada. Verifique a chave, o secret, a hora (±300 s), o nonce e a assinatura; o suporte consegue identificar a causa exata através do request_id. |
| 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, order_in_progress, service_not_active | Conflito. O Idempotency-Key já foi utilizado com outro corpo ou noutro endpoint (idempotency_conflict, reason in_progress enquanto o primeiro pedido ainda está em curso), outra encomenda da sua conta ainda está a ser processada (reason order_in_progress, respeite o cabeçalho Retry-After) ou o serviço não está num estado que permita a ação (service_not_active, ver service_status). |
| 413 | payload_too_large | Body do pedido superior a 65 536 bytes. É rejeitado antes da autenticação. |
| 422 | unprocessable | Pedido compreendido, mas não executável. reason billing_cycle_not_available: o produto não é oferecido neste ciclo de faturação. reason zero_total_not_allowed: a encomenda seria gratuita sem um motivo válido, como um código promocional. |
| 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.)credit_apply_failed(Não foi possível aplicar o crédito à fatura. Nada foi cobrado e a encomenda foi cancelada. Tente novamente com um novo Idempotency-Key ou contacte o suporte.)client_not_found(ID da conta não encontrado (praticamente nunca deve ocorrer, contate o suporte).)
