Todos los errores siguen el RFC 7807. El cuerpo es application/problem+json con los campos type, title, status, detail, request_id y, opcionalmente, reason o 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 | Validación de entrada fallida. Consulte errors[] para el detalle de cada campo. |
| 401 | auth_failed | Autenticación fallida. La respuesta siempre contiene reason unauthorized (o ip_not_allowed si la clave está restringida a otras direcciones IP) y deliberadamente no revela nada más. Compruebe la clave, el secreto, la hora (±300 s), el nonce y la firma; el soporte puede consultar la causa exacta mediante el request_id. |
| 402 | payment_required | Pago requerido. reason, véase a continuación. |
| 403 | forbidden_scope | Permiso ausente. reason: missing_scope. |
| 404 | not_found | El recurso no existe o no es visible para esta clave (evita la enumeración de clientes). |
| 409 | idempotency_conflict, order_in_progress, service_not_active | Conflicto. O bien el Idempotency-Key ya se utilizó con otro cuerpo u otro endpoint (idempotency_conflict, reason in_progress mientras la primera solicitud sigue en curso), o bien otro pedido de su cuenta todavía se está procesando (reason order_in_progress, respete la cabecera Retry-After), o bien el servicio no está en un estado que permita la acción (service_not_active, véase service_status). |
| 413 | payload_too_large | Cuerpo de la solicitud superior a 65.536 bytes. Se rechaza antes de la autenticación. |
| 422 | unprocessable | Solicitud comprendida pero no ejecutable. reason billing_cycle_not_available: el producto no se ofrece en este ciclo de facturación. reason zero_total_not_allowed: el pedido sería gratuito sin un motivo válido, como un código promocional. |
| 429 | rate_limited | Límite de tasa superado. Respete la cabecera Retry-After. |
| 500 | internal_error | Error interno del servidor. Indique request_id al contactar con soporte para correlacionar con el registro de auditoría. |
Motivos de pago requerido (HTTP 402)
Cuando el pedido no se puede pagar, la API devuelve HTTP 402 con un reason legible por máquina en el cuerpo JSON.
insufficient_credit_and_no_card(Saldo insuficiente y sin tarjeta registrada. Solución: recargar el saldo o añadir una tarjeta en el portal de clientes.)card_declined(Tarjeta rechazada por el banco o la pasarela. Solución: probar con otra tarjeta o contactar con su banco.)credit_apply_failed(No se pudo aplicar el saldo a la factura. No se ha cobrado nada y el pedido se ha cancelado. Vuelva a intentarlo con un nuevo Idempotency-Key o contacte con el soporte.)client_not_found(Identificador de cuenta no encontrado (no debería ocurrir en la práctica, contacte con soporte).)
