Docs · Desde tu sistema Descargar .md
Errores y rechazos
Cuando la API responde con error
El cuerpo siempre trae error y, a veces, detail:
json
{ "error": "validation", "detail": { "fieldErrors": { "monto": ["Number must be greater than 0"] } } }| HTTP | error | Qué pasó | Qué haces |
|---|---|---|---|
| 400 | validation | Un campo falta o no es válido. Al listar enlaces con un filtro que no se entiende, viene además parametro con su nombre y detail es un texto | Revisa detail (y parametro) |
| 401 | unauthorized | Falta la llave, está mal escrita o fue revocada | Revisa x-switch-key |
| 403 | comercio_suspendido | Tu comercio está suspendido: no se pueden crear enlaces ni lotes (ni de prueba ni de producción) | Escríbenos para reactivarlo |
| 403 | requiere_llave_live | Con una llave de prueba intentaste crear o revocar una llave de producción | Usa una sk_live_ → Llaves |
| 404 | not_found | Ese cobro no existe o no es de tu comercio | Revisa el id |
| 409 | p. ej. item_duplicado | Conflicto: en un lote, una idempotency_key de ítem ya usada | Revisa detail |
| 409 | limite_webhooks | Ya tienes 10 webhooks registrados | Borra uno que no uses → Webhooks |
| 422 | destino_bloqueado | La URL del webhook apunta a una red interna | Usa una URL pública → Webhooks |
| 400 / 422 / 503 | split_… | El pago dividido no está activo, el reparto no es válido, una cuenta no está aprobada en el portal o un control de seguridad la frena | → Pago dividido |
| 409 | idempotency_key_en_uso | Esa idempotency_key ya la usaste con una llave del otro modo (prueba o producción) | Usa otra llave de idempotencia |
| 409 | tope_diario_excedido / tope_acumulado_excedido | Al pedir la clave de pago (página de pago, WhatsApp Flow o POST /cobrar/token): ese cobro pasaría el tope de lo que tu cuenta puede recibir hoy o en total. Trae motivo (el texto para tu cliente); con tu llave, además tope y usado (en Bs) y, si tu tope está en dólares, topes_moneda, tope_usd y tasa_bcv | Tu cliente no paga ahora; escríbenos si necesitas más tope → Límites |
| 429 | — | Pasaste el límite de peticiones | Espera y reintenta → Límites |
| 503 | cierre_bancario | En la página de pago, al pedir la clave entre las 11:45 p. m. y la 1:30 a. m. (hora de Venezuela): los bancos están en su cierre diario. Trae motivo (el texto para tu cliente) y reintentar_en (segundos hasta que termine) | Tu cliente paga después de la 1:30 a. m. con el mismo enlace → Cierre diario |
| 5xx | — | Falla nuestra | Reintenta con la misma idempotency_key |
Cuando el banco rechaza el pago
Eso no te llega como error de la API: tu cliente lo ve en la página de pago ("El banco no aprobó el pago") y puede intentarlo otra vez con una clave nueva. El cobro sigue pendiente hasta que lo pague o venza.
Si tu comercio está suspendido
Mientras dure la suspensión:
- Crear enlaces (
POST /links) o lotes (POST /lotes) responde403con{ "error": "comercio_suspendido" }. - Un enlace que estaba
pendienteno se puede empezar a pagar: tu cliente ve "Este comercio no está recibiendo pagos" y no se le cobra nada. - Lo que ya se estaba pagando (
cobrando,procesando,revision) termina normalmente, y el dinero de lo ya pagado se te sigue liquidando. - Consultar y listar tus enlaces sigue funcionando.
Reintentar sin duplicar
Si una creación falla por red o por un 5xx, reintenta con la misma idempotency_key: si el primer intento sí llegó, recibes el mismo enlace en vez de uno nuevo.
json
{ "monto": 150, "concepto": "Pedido #1024", "idempotency_key": "pedido-1024" }