Errores

Hay dos tipos de errores, y conviene distinguirlos:

Errores de la API — tu petición está mal formada o no autenticada (HTTP 4xx). Se resuelven del lado de tu integración.
Rechazos del cobro — la petición fue correcta, pero el banco/tarjeta rechazó el pago. La transacción queda declined/failed con un motivo.

Códigos HTTP

HTTP	Significado
`200` / `201`	Operación procesada (en cobros, incluye aprobado o rechazado).
`400 Bad Request`	Datos inválidos en la petición (ver `message`).
`401 Unauthorized`	Clave de API ausente, inválida o revocada.
`403 Forbidden`	La clave no tiene permiso para esa operación.
`404 Not Found`	El recurso no existe (sesión, transacción…).
`409 Conflict`	Estado incompatible (p. ej. sesión ya usada, comercio sin aprovisionar).
`410 Gone`	La sesión de pago expiró. Genera una nueva.
`500`	Error interno. Reintenta; si persiste, contacta a soporte.

Forma de un error de la API


{
  "statusCode": 400,
  "error": "Bad Request",
  "message": ["amountMinor must not be less than 1", "currency must be a valid enum value"]
}

message puede ser un texto o una lista de validaciones.

Rechazos del cobro

Cuando una transacción queda declined o failed, en GET /v1/transactions verás:

errorCode — el código del procesador.
errorReason — el motivo técnico (para tu depuración).

Además, el comprador ya recibió en el checkout un mensaje limpio en español. La siguiente tabla resume los códigos más comunes.

El comprador puede resolverlo (no requiere soporte)

`errorCode`	Motivo	Qué hacer
`0051`, `0364`, `0374`–`0376`	Fondos insuficientes	Sugerir otra tarjeta.
`0061`, `0365`, `0369`	Excede el límite de la tarjeta	Sugerir otra tarjeta o monto menor.
`0054`, `120`	Tarjeta vencida	Usar otra tarjeta.
`0055`, `130`, `230`	CVV incorrecto	Reingresar el CVV.
`0014`, `80`, `9013`	Número de tarjeta inválido	Verificar los datos.
`110`	Fecha de vencimiento inválida	Verificar el vencimiento.
`90`, `91`, `0341`	Documento del titular no coincide	Verificar la cédula del titular.
`0057`, `140`, `311`	La tarjeta no permite la operación	Usar otra tarjeta.
`245`, `9014`, `9015`, `150`	Bloqueada por el banco / 2FA	Comunicarse con el banco emisor.

Requiere tu atención (configuración o procesador)

Estos no los puede resolver el comprador — revisa tu integración o contacta a soporte. Seif también te avisa por correo automáticamente cuando ocurren.

`errorCode`	Motivo	Qué revisar
`220`	ApiKey de Sitef no válido	Credenciales del procesador.
`40`, `49`	Código de comercio inválido	Configuración del comercio (merchant id).
`46`	IP del cliente errada	IP de egreso autorizada (whitelist).
`170`, `190`	Moneda errada	Enviar la sesión en `VES`.
`210`	Número de factura duplicado	Idempotencia del cobro.
`9001`–`9012`	Error interno del procesador	Reintentar; si persiste, soporte.

Nunca le muestres al comprador el errorCode ni el errorReason. Esos son para tu depuración. El mensaje apto para el comprador ya lo entrega el checkout.

Recomendaciones

Suscríbete a webhooks (charge.declined, charge.failed) para reaccionar al instante.
En caso de failed, reintenta más tarde (puede ser una falla transitoria del procesador).
Registra el errorCode + errorReason en tus logs para detectar patrones.
Ante un código que no reconozcas, contáctanos: lo mapeamos y mejoramos el mensaje.