Skip to main content

​
Formato de errores

Todas las respuestas de error de la API siguen un formato JSON consistente: 
{
  "error": {
    "code": "INVALID_REQUEST",
    "message": "El campo 'amount' es requerido",
    "status": 400
  }
}

​
Códigos HTTP

CódigoSignificadoAcción recomendada
200ÉxitoProcesa la respuesta normalmente
201Recurso creadoEl recurso fue creado exitosamente
400Petición inválidaRevisa los parámetros enviados
401No autenticadoVerifica tu token o API key
403Sin permisosNo tienes acceso a este recurso
404No encontradoEl recurso no existe
409ConflictoOperación duplicada o estado inconsistente
422Validación fallidaRevisa el formato de los datos
429Rate limitEspera antes de reintentar
500Error del servidorReintenta con backoff exponencial

​
Códigos de error comunes

​
Autenticación

CódigoDescripción
TOKEN_EXPIREDEl accessToken ha expirado. Renuévalo con refreshToken
TOKEN_INVALIDEl token no es válido
REFRESH_TOKEN_EXPIREDEl refreshToken expiró. El usuario debe hacer login
API_KEY_REVOKEDLa API key fue revocada

​
Transacciones

CódigoDescripción
INSUFFICIENT_FUNDSFondos insuficientes en la cuenta
INVALID_ACCOUNTNúmero de cuenta no válido
BANK_UNAVAILABLEEl banco destino no está disponible
TRANSFER_LIMIT_EXCEEDEDSe excedió el límite de transferencia

​
Merchants

CódigoDescripción
MERCHANT_NOT_FOUNDEl merchant no existe
MERCHANT_INACTIVEEl merchant está desactivado
RIF_ALREADY_EXISTSYa existe un merchant con ese RIF
MEMBER_ALREADY_EXISTSEl usuario ya es miembro del merchant

​
Reintentos

Para errores 5xx y 429, implementa reintentos con backoff exponencial: 
async function apiCall(url, options, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    const response = await fetch(url, options);

    if (response.status === 429 || response.status >= 500) {
      const delay = Math.pow(2, i) * 1000; // 1s, 2s, 4s
      await new Promise(resolve => setTimeout(resolve, delay));
      continue;
    }

    return response;
  }
  throw new Error('Max retries exceeded');
}

​
Paginación

Los endpoints que retornan listas usan paginación con los siguientes parámetros:
ParámetroDefaultDescripción
page1Número de página
limit50Elementos por página
search-Búsqueda por texto
status-Filtrar por estado
environment-"live" o "test"
curl "https://api.venepagos.com.ve/api/v1/merchants?page=2&limit=10&status=ACTIVE" \
  -H "Authorization: Bearer TU_ACCESS_TOKEN"