Saltar al contenido principal

Errores

Cuando una solicitud falla, la API devuelve un estado HTTP de error y una respuesta estructurada con uno o varios errores en data.errors.

Respuesta de error​

{
"status": "error",
"data": {
"errors": [
{
"errorMessage": "resourceNotFound",
"errorType": "GENERAL",
"errorId": "3f69d9b6",
"errorDescription": "Resource not found",
"errorField": null,
"params": [],
"requestParams": {}
}
]
}
}
CampoDescripción
errorMessageCódigo de error legible por máquina. Úsalo en tu gestión de errores.
errorTypeCategoría del error: FIELD (un campo no es válido, consulta errorField), FORM (la solicitud en conjunto) o GENERAL.
errorIdIdentificador de este error. Regístralo e inclúyelo en tus consultas a soporte.
errorDescriptionDescripción legible para personas. No la uses en la lógica del programa: el texto puede cambiar.
errorFieldEl campo de la solicitud relacionado con el error, si lo hay.
paramsParámetros adicionales del error, si los hay.
requestParamsParámetros de la solicitud relacionados con el error, si los hay.

Códigos de error frecuentes​

La lista incluye los códigos que una integración suele tener que gestionar. No está completa: un método puede devolver otros códigos. Trata un errorMessage desconocido como un error general y registra su errorId.

errorMessageQué significa
missingRequestParameterFalta un parámetro obligatorio.
methodArgumentTypeMismatchUn parámetro tiene un tipo incorrecto, por ejemplo texto en lugar de un número.
httpMessageNotReadableEl cuerpo de la solicitud no es un JSON válido o no coincide con la estructura esperada.
unrecognizedFieldEl cuerpo de la solicitud contiene un campo que el método no acepta.
badParametersExceptionUno o varios parámetros no son válidos.
badFormatAmountExceptionEl monto tiene un formato no válido.
notEnoughMoneyExceptionLa billetera de origen no tiene fondos suficientes.
limitPerTransactionExceptionEl monto supera el límite por transacción.
limitPerMonthExceptionLa transacción supera el límite mensual.
walletDoesNotExistLa billetera de la solicitud no existe.
walletCurrencyIncorrectExceptionLa moneda de la billetera no coincide con la solicitud.
recipientDoesNotExistExceptionLa cuenta del destinatario no existe.
paymentMethodNotAvailableForMerchantApiEl método de pago no está disponible para tu API.
resourceNotFoundEl endpoint no existe.
attemptsHaveEndedExceptionLa cuenta agotó su límite de solicitudes por hora. Consulta Límite de solicitudes.
tryAgainAfterAWhileLos datos están bloqueados temporalmente. Vuelve a intentarlo más tarde.
serviceTemporaryUnavailableUn servicio no está disponible temporalmente. Vuelve a intentarlo más tarde.
internalServerErrorError inesperado del servidor.

Códigos de estado HTTP​

EstadoSignificado
400La solicitud tiene un formato incorrecto, contiene parámetros no válidos o no se puede procesar. También se devuelve cuando no se encuentra un pedido u otra entidad.
401Faltan los encabezados de autenticación o no son válidos, o la cuenta agotó su límite de solicitudes por hora (attemptsHaveEndedException).
404No se encontró el endpoint solicitado.
405El endpoint no admite este método HTTP (httpMethodNotAllowed).
409Los datos están bloqueados temporalmente (tryAgainAfterAWhile).
415El Content-Type de la solicitud no es compatible (unknownContentType).
500Error inesperado del servidor (internalServerError).
503Un servicio no está disponible temporalmente (serviceTemporaryUnavailable).

No deduzcas el código de error solo a partir del estado HTTP: el mismo estado puede llegar con distintos valores de errorMessage.

Gestionar los errores​

  • Registra el errorId de cada error.
  • Revisa errorField para encontrar el campo que debes corregir.
  • Después de un 401, revisa el nombre de la API, el email de la cuenta, el token y la hora UTC del servidor.
  • Si la API no tiene permiso para la operación o tu servidor no puede llamarla, revisa los permisos de la API y su lista blanca de IP en la sección de herramientas de pago.

Reintentar con seguridad​

Los errores se dividen en dos grupos:

  • Temporales — 409 (tryAgainAfterAWhile), 503 (serviceTemporaryUnavailable) y los tiempos de espera agotados. Reintenta las solicitudes de lectura y de validación con una pausa cada vez mayor entre intentos. Para las solicitudes que crean una transacción o una factura, consulta más abajo.
  • Permanentes — errores de autenticación y de parámetros. Corrige la solicitud en lugar de repetirla.

Las solicitudes de validación (/api/withdrawal/validation/…) y las consultas no crean nada y se pueden repetir.

La Merchant API no tiene clave de idempotencia. Una solicitud que crea una transacción o una factura puede agotar el tiempo de espera o fallar después de que la API ya la procesó, y repetirla puede crear una segunda. Después de un tiempo de espera agotado o un error 5xx, comprueba si se creó antes de repetirla:

  • Para los pagos, revisa el historial de transacciones y el saldo de la billetera. Consulta Obtener historial de transacciones. Cada solicitud de pago que pasa la validación crea una transacción nueva, aunque repita una anterior.
  • Para las facturas, busca el pedido por tu orderId. Consulta Obtener pedido de pago. Si envías sciName, Volet.com rechaza una segunda factura con el mismo orderId para ese Hosted Checkout.

Si sigue sin estar claro si un pago se creó, contacta a soporte antes de volver a enviarlo.

  • Introducción — URL base, autenticación y formato de las solicitudes
  • Estados — estados de las transacciones y de los pagos