Manejo de errores
La API de iPagos sigue las convenciones HTTP estándar. Cualquier respuesta no 2xx
incluye un objeto error en JSON con información detallada y accionable.
Códigos HTTP
| Código | Significado | Acción sugerida |
|---|---|---|
| 200 | OK | Procesar la respuesta. |
| 201 | Recurso creado | Persistir el id devuelto. |
| 400 | Petición inválida | Revisar parámetros enviados. |
| 401 | Autenticación inválida | Verificar llave o IP permitida. |
| 402 | Tarjeta rechazada | Mostrar mensaje al usuario y reintentar con otro medio. |
| 404 | Recurso no encontrado | Verificar id. |
| 409 | Conflicto (idempotencia) | Reusar la respuesta original. |
| 429 | Rate limit | Esperar el tiempo de Retry-After. |
| 5xx | Error de iPagos | Reintentar con backoff exponencial. |
Estructura de un error
{
"error": {
"type": "card_error",
"code": "insufficient_funds",
"message": "La tarjeta no tiene fondos suficientes.",
"doc_url": "https://docs.ipagos.lat/errores#insufficient_funds",
"request_id": "req_8B2nM1Q9TfYr",
"param": "source"
}
}Tipos de error
api_error — falla interna de iPagos. Reintentar con backoff.card_error — el banco emisor rechazó la tarjeta. Mostrar el message al usuario.invalid_request_error — parámetros incorrectos o faltantes.authentication_error — la llave es inválida, expiró o no tiene permisos.idempotency_error — la Idempotency-Key se reutilizó con un cuerpo distinto.rate_limit_error — sobrepasaste el límite de peticiones por minuto.request_id al contactar a soporte. Permite reconstruir exactamente
qué ocurrió en nuestros sistemas.