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": {}
}
]
}
}
| Campo | Descripción |
|---|---|
errorMessage | Código de error legible por máquina. Úsalo en tu gestión de errores. |
errorType | Categoría del error: FIELD (un campo no es válido, consulta errorField), FORM (la solicitud en conjunto) o GENERAL. |
errorId | Identificador de este error. Regístralo e inclúyelo en tus consultas a soporte. |
errorDescription | Descripción legible para personas. No la uses en la lógica del programa: el texto puede cambiar. |
errorField | El campo de la solicitud relacionado con el error, si lo hay. |
params | Parámetros adicionales del error, si los hay. |
requestParams | Pará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.
errorMessage | Qué significa |
|---|---|
missingRequestParameter | Falta un parámetro obligatorio. |
methodArgumentTypeMismatch | Un parámetro tiene un tipo incorrecto, por ejemplo texto en lugar de un número. |
httpMessageNotReadable | El cuerpo de la solicitud no es un JSON válido o no coincide con la estructura esperada. |
unrecognizedField | El cuerpo de la solicitud contiene un campo que el método no acepta. |
badParametersException | Uno o varios parámetros no son válidos. |
badFormatAmountException | El monto tiene un formato no válido. |
notEnoughMoneyException | La billetera de origen no tiene fondos suficientes. |
limitPerTransactionException | El monto supera el límite por transacción. |
limitPerMonthException | La transacción supera el límite mensual. |
walletDoesNotExist | La billetera de la solicitud no existe. |
walletCurrencyIncorrectException | La moneda de la billetera no coincide con la solicitud. |
recipientDoesNotExistException | La cuenta del destinatario no existe. |
paymentMethodNotAvailableForMerchantApi | El método de pago no está disponible para tu API. |
resourceNotFound | El endpoint no existe. |
attemptsHaveEndedException | La cuenta agotó su límite de solicitudes por hora. Consulta Límite de solicitudes. |
tryAgainAfterAWhile | Los datos están bloqueados temporalmente. Vuelve a intentarlo más tarde. |
serviceTemporaryUnavailable | Un servicio no está disponible temporalmente. Vuelve a intentarlo más tarde. |
internalServerError | Error inesperado del servidor. |
Códigos de estado HTTP
| Estado | Significado |
|---|---|
400 | La 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. |
401 | Faltan los encabezados de autenticación o no son válidos, o la cuenta agotó su límite de solicitudes por hora (attemptsHaveEndedException). |
404 | No se encontró el endpoint solicitado. |
405 | El endpoint no admite este método HTTP (httpMethodNotAllowed). |
409 | Los datos están bloqueados temporalmente (tryAgainAfterAWhile). |
415 | El Content-Type de la solicitud no es compatible (unknownContentType). |
500 | Error inesperado del servidor (internalServerError). |
503 | Un 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
errorIdde cada error. - Revisa
errorFieldpara 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íassciName, Volet.com rechaza una segunda factura con el mismoorderIdpara ese Hosted Checkout.
Si sigue sin estar claro si un pago se creó, contacta a soporte antes de volver a enviarlo.
Relacionado
- Introducción — URL base, autenticación y formato de las solicitudes
- Estados — estados de las transacciones y de los pagos