Errores

Cómo reporta fallas la API de Vecnet — la forma del error en JSON, los códigos de estado HTTP, las tarjetas rechazadas y los errores de base de datos.

Toda respuesta de error de la API de Vecnet es un objeto JSON con un solo campo error de texto. No hay sobre anidado, ni code, ni arreglo details: solo un mensaje legible que puedes mostrar o registrar.

{
  "error": "Merchant not found"
}

Cada respuesta lleva un encabezado X-Request-Id que repite el request_id registrado en la bitácora de auditoría. Inclúyelo al reportar un problema para que la petición pueda reconstruirse.

Códigos de estado

Estado	Significado
`400`	Petición inválida: JSON mal formado, campos faltantes o inválidos.
`401`	No autorizado: credenciales faltantes o inválidas.
`402`	Tarjeta rechazada: solo en endpoints de pago; el cuerpo trae `declined: true`.
`403`	Prohibido: autenticado, pero sin permiso.
`404`	No encontrado: el recurso no existe o está fuera del alcance de tu comercio.
`409`	Conflicto: un conflicto de unicidad o de estado.
`410`	Retirado: un endpoint descontinuado (ve la nota más abajo).
`500`	Error del servidor: una falla inesperada de nuestro lado.
`502`	Error aguas arriba: una dependencia del servicio no respondió.
`503`	Servicio no disponible: un problema de correo o de configuración.

Tarjetas rechazadas

Una tarjeta rechazada no es un 400. Los endpoints de pago devuelven HTTP 402 con declined: true en el cuerpo, para que distingas un rechazo genuino de una petición mal formada.

{
  "error": "Card declined",
  "declined": true
}

Endpoints retirados (410 Gone)

El checkout alojado ya no recibe datos de tarjeta por un endpoint pay directo. El pagador completa el pago en la página alojada y tu integración conoce el resultado por un webhook o consultando la sesión. Las llamadas a las rutas antiguas /api/public/checkout-sessions/:id/pay y /api/public/links/:id/pay devuelven 410 Gone.

Errores de base de datos

Las violaciones de restricciones en la base de datos se traducen al código HTTP correspondiente antes de llegar a ti, así que siempre recibes la misma forma con un solo error:

Condición	Estado HTTP
Violación de unicidad	`409` Conflicto
Campo obligatorio ausente	`400` Petición inválida

Manejar errores en código

Ramifica por código de estado y después lee la cadena error. Trata el 402 de forma especial cuando llames a un endpoint de pago.

const res = await fetch("https://api.vecnet.io/api/transactions", {
  headers: { Authorization: "Token vk_live_1a2b3c4d5e6f7a8b9c0d" },
});

const body = await res.json();

if (!res.ok) {
  const requestId = res.headers.get("X-Request-Id");
  throw new Error(`La petición ${requestId} falló (${res.status}): ${body.error}`);
}

Ante cualquier 5xx, reintenta con espera exponencial y captura el encabezado X-Request-Id: permite al equipo encontrar tu petición exacta en la bitácora. Si los errores persisten, revisa la página de estado.