Códigos de error

Todas las respuestas de la API de VelaFi son JSON. Una llamada exitosa devuelve HTTP 200 y un sobre con code igual a 200, msg igual a "SUCCESS" y el resultado en data:

{
  "code": 200,
  "msg": "SUCCESS",
  "data": { ... }
}

Algunos endpoints, entre ellos Aumentar límite (POST /v2/upgrade/limits), devuelven "code": 0 y "msg": "success" cuando la operación es exitosa. Considera exitosa una respuesta HTTP 200 con code 200 o 0.

Formato de la respuesta de error

Una llamada fallida devuelve un estado HTTP distinto de 200. Los errores de autenticación, validación, límite de solicitudes y de negocio usan HTTP 400. El cuerpo contiene un code de error y un msg en inglés. Los códigos de error son negativos, excepto 30012. En la mayoría de los errores, el mismo código se repite en el encabezado de respuesta error_code. Los cuerpos de error no tienen campo data.

HTTP/1.1 400 Bad Request
Content-Type: application/json;charset=UTF-8
error_code: -1002

{"code":-1002,"msg":"You are not authorized to execute this request"}

integer

El código de error. Usa este valor, o el encabezado error_code, para decidir cómo manejar el error.

string

Una descripción del error en inglés. Puede contener valores de tiempo de ejecución, así que no compares contra el texto exacto.

string

Opcional. Detalle adicional, presente solo en algunos errores.

object

Opcional. Detalle a nivel de campo, presente solo en algunos errores.

Los mensajes de las tablas siguientes muestran marcadores de posición como {0}, {1} o %s. Por lo general, VelaFi los reemplaza con el nombre del campo, el valor o el límite que causó el error, pero algunas respuestas devuelven el marcador tal cual (por ejemplo Parameter {0} is invalid). Básate en code, no en msg.

Códigos de estado HTTP

Estado HTTP	Cuándo	Cuerpo
`200`	La solicitud fue exitosa.	Sobre de éxito
`400`	Errores de autenticación, validación, límite de solicitudes y de negocio.	`{"code": <error code>, "msg": "..."}`
`404`	La ruta no existe.	No es el sobre de VelaFi: `{"timestamp": ..., "status": 404, "error": "Not Found", "message": "", "path": "..."}`
`405`	La ruta existe, pero no acepta este método HTTP.	Misma forma que `404`, con `"status": 405`
`500`	Un error inesperado del servidor.	`{"code": -1001, "msg": "Internal error."}`

Los fallos de autenticación y los rechazos por límite de solicitudes no usan 401, 403 ni 429. Un token ausente, expirado o inválido devuelve HTTP 400 con el código -1002 o -1022, y exceder un límite de solicitudes devuelve HTTP 400 con el código -1006. Revisa code, no solo el estado HTTP.

Resultado desconocido: verifica antes de reintentar

Las respuestas siguientes no indican si la solicitud se llevó a cabo. Si recibes una de ellas en una llamada que crea o modifica algo, como crear o confirmar una orden, es posible que la operación se haya completado. Antes de reintentar, llama a Listar órdenes (GET /v2/orders) para el periodo correspondiente y busca tu clientId. Reintenta solo si la orden no aparece.

Código	`msg`	Por qué el resultado es desconocido
`-1001`	`Internal error.`	Ocurrió un error inesperado mientras se procesaba la solicitud. Es posible que parte de la operación ya se haya completado.
`-1006`	`Execution status unknown.`	VelaFi devuelve este código para cualquier error del backend que no tenga un código específico de Open API, incluidas las fallas del backend.
`-1007`	`Timeout waiting for response from backend server.`	El backend no respondió a tiempo. Es posible que aun así haya completado la operación.
`30012`	`Network busy, Try again later`	Demasiadas solicitudes concurrentes al mismo endpoint. Es posible que la solicitud aun así se procese. Esta respuesta no tiene encabezado `error_code`.

-1006 no se limita a resultados inciertos. También se devuelve en algunos casos de entrada inválida en endpoints de solo lectura (por ejemplo, un corredor no admitido en GET /v2/base/fiat/payments) y cuando excedes un límite de solicitudes. En llamadas GET de solo lectura, revisa tu entrada y reintenta. En llamadas que crean o modifican algo, verifica primero como se describe arriba.

Errores de autenticación y de solicitud

Estos errores provienen de la generación de tokens, la verificación de tokens y el análisis de la solicitud. GET /v2/token/generate también devuelve -5033 (consulta Errores de KYC/KYB más abajo) cuando el acceso a la API no está habilitado para tu cuenta.

Código	`msg`	Significado
`-1002`	`You are not authorized to execute this request`	Falta el encabezado `X-BH-TOKEN`. En `/v2/token/generate`, falta el encabezado `X-BH-APIKEY` o no tiene un formato de clave de API válido.
`-1022`	`Signature for this request is not valid.`	El valor de `X-BH-TOKEN` no se reconoce, por ejemplo porque expiró. En `/v2/token/generate`, la clave de API es desconocida o la `signature` no coincide. Genera un token nuevo.
`-1023`	`Please set IP whitelist before using API`	La clave de API no tiene lista blanca de IP. `/v2/token/generate` y la mayoría de los demás endpoints la requieren.
`-2015`	`Invalid API-key, IP, or permissions for action.`	La clave de API o su cuenta está deshabilitada. En `/v2/token/generate`, también se devuelve cuando la IP que llama no está en la lista blanca de IP de la clave.
`-2019`	`Request ip is not in the whitelist`	En endpoints autenticados con token, la IP que llama no está en la lista blanca de IP de la clave de API.
`-1000`	`An unknown error occured while processing the request.`	No se pudieron verificar las credenciales por otro motivo.
`-1005`	`No Permission`	El tipo de cuenta de la clave de API no tiene permitido llamar a este endpoint.
`-1004`	`Bad request`	La solicitud está mal formada; por ejemplo, un parámetro tiene el tipo incorrecto o el cuerpo JSON no se puede analizar. Cuando falta un parámetro de consulta obligatorio, `msg` es `Missing required parameter '<name>'`.
`-1103`	`An unknown parameter was sent.`	Se llamó a `/v2/token/generate` sin ningún parámetro de consulta.
`-1130`	`Data sent for paramter '%s' is not valid.`	Falta un campo o no pasa la validación. `%s` es el nombre del campo. La API devuelve la ortografía `paramter` tal cual.
`-1189`	`Illegal characters found in parameter, illegal content is '%s'.`	El cuerpo de la solicitud no se pudo convertir a los tipos esperados. `%s` es el texto de error del analizador.

Errores de parámetros

Los errores de parámetros indican que uno o más campos de la solicitud no pasaron la validación básica: tipo incorrecto, longitud incorrecta, formato incorrecto o un envío duplicado.

Código	`msg`	Significado
`-4001`	`Request parameter verification error`	Un parámetro de la solicitud no pasó la validación
`-4010`	`Parameter {0} is invalid`	El parámetro `{0}` es inválido
`-4011`	`Parameter {0} exceeds the limit length of {1}`	El parámetro `{0}` es más largo que `{1}`
`-4012`	`Parameter {0} exceeds the limit quantity of {1}`	El parámetro `{0}` tiene más de `{1}` elementos
`-4013`	`The length of parameter {0} must be {1} characters`	El parámetro `{0}` debe tener `{1}` caracteres
`-4014`	`The length of parameter {0} must be {1} letters`	El parámetro `{0}` debe tener `{1}` letras
`-4015`	`The length of parameter {0} must be {1} digits`	El parámetro `{0}` debe tener `{1}` dígitos
`-4016`	`The parameter {0} must be {1} at position {2}`	El parámetro `{0}` debe tener `{1}` en la posición `{2}`
`-4021`	`Parameter {0} is not numeric type`	El parámetro `{0}` debe ser numérico
`-4022`	`Parameter {0} is not alphabetic type`	El parámetro `{0}` debe ser alfabético
`-4023`	`Parameter {0} is not alphanumeric type`	El parámetro `{0}` debe ser alfanumérico
`-4024`	`Parameter {0} is an invalid ISO 3166-1 code`	El parámetro `{0}` no es un código ISO 3166-1 válido
`-4025`	`Parameter {0} is an invalid ISO 3166-2 code`	El parámetro `{0}` no es un código ISO 3166-2 válido
`-4026`	`Parameter {0} is an invalid account owner type`	El parámetro `{0}` no es un tipo de titular de cuenta válido
`-4040`	El motivo específico, por ejemplo `Only POL or SPL20 is supported for network.`	Error general. `msg` describe el motivo
`-5040`	`Invalid value of amount`	Un valor de monto es inválido
`-1174`	`Repeated submit request.`	La misma solicitud se envió repetidamente

Errores de métodos de pago

Los errores de métodos de pago ocurren cuando un método de pago no existe, está mal configurado o no es compatible con la operación o la plataforma solicitada.

Código	`msg`	Significado
`-4027`	`The payment method doesn't exist`	El método de pago no existe
`-5001`	`Please select automatic payment method`	Selecciona un método de pago automático
`-5002`	`Payment method has no bank account information`	El método de pago no tiene información de cuenta bancaria
`-5003`	`Payment method cannot be modified temporarily`	El método de pago no se puede modificar en este momento
`-5004`	`Payment method does not have automatic bank API configured`	El método de pago no tiene configurada una API bancaria automática
`-5014`	`Bank card information matches merchant's card information`	Los datos de la cuenta bancaria coinciden con la cuenta propia del comercio
`-5017`	`Invalid payment method`	Método de pago inválido
`-5018`	`Payment method does not match the platform configuration, please choose again`	El método de pago no coincide con la configuración de la plataforma
`-5048`	`The payment type invalid`	El tipo de pago es inválido
`-5053`	`Account already exists`	La cuenta ya existe
`-5054`	`Failed to add a payment method, please go to configuration page to edit and submit it again.`	No se pudo agregar el método de pago
`-2017`	`The email already exists.`	El correo electrónico ya existe
`-2018`	`Illegal email`	La dirección de correo electrónico es inválida

Errores de comercio

Los errores de comercio se relacionan con el ciclo de vida y la configuración de los comercios, incluidos fallos de registro, registros inexistentes y problemas con el estado de la cuenta.

Código	`msg`	Significado
`-5005`	`Merchant already exists`	El comercio ya existe
`-5006`	`Merchant does not exist`	El comercio no existe
`-5007`	`Invalid merchant information`	La información del comercio es inválida
`-5015`	`The CUIT does not match with your selected merchant`	El CUIT no coincide con el comercio seleccionado
`-5038`	`The merchant account not exists`	La cuenta del comercio no existe
`-5039`	`The merchant settings not exists`	La configuración del comercio no existe
`-5056`	`Payment information doesn't match merchant configuration.`	La información de pago no coincide con la configuración del comercio
`-5059`	`Merchant registration failure.`	El registro del comercio falló
`-5059`	`Please first pass the Liveness authentication`	Primero se debe completar la prueba de vida. Comparte su código con la fila anterior
`-5064`	`It has exceeded the current maximum number of merchants that can be created (maximum: {0}).`	Alcanzaste el número máximo de comercios (`{0}`)
`-5065`	`The merchant channel invalid`	El canal del comercio es inválido
`-5066`	`The merchant's account is currently under verification`	La cuenta del comercio está en verificación
`-5067`	`The merchant account certification process has been end`	El proceso de verificación de la cuenta del comercio terminó
`-5069`	`The merchant name already exists`	El nombre del comercio ya existe
`-5070`	`The merchant has not activated the automatic mode account for {0}. Please activate it and try again.`	El comercio no ha activado la cuenta en modo automático para `{0}`
`-5071`	`The merchant fiat account is invalid`	La cuenta fiat del comercio es inválida
`-5077`	`The Merchant has been disabled.`	El comercio fue deshabilitado
`-5083`	`The Merchant has been closed.`	El comercio fue cerrado

Errores de cuentas fiat y cuentas virtuales

Estos errores se relacionan con la activación y el uso de las cuentas fiat y las cuentas virtuales de un comercio.

Código	`msg`	Significado
`-5073`	`The merchant did not pass the KYC verification.`	El comercio no ha aprobado la verificación KYC
`-5074`	`The merchant fiat account has been activated.`	La cuenta fiat ya está activada
`-5075`	`The merchant fiat account activation failed.`	La activación de la cuenta fiat falló
`-5076`	`The Merchant fiat account has been closed.`	La cuenta fiat fue cerrada
`-5078`	`The Merchant fiat account has been disabled.`	La cuenta fiat fue deshabilitada
`-5079`	`No activation permission for the current fiat account.`	No tienes permiso para activar esta cuenta fiat
`-5084`	`This fiat currency does not support multiple virtual accounts.`	Esta moneda fiat no admite múltiples cuentas virtuales
`-5085`	`Virtual account is under verification.`	La cuenta virtual está en verificación
`-5086`	`Virtual account has been activated.`	La cuenta virtual ya está activada
`-5087`	`Virtual account alias is invalid.`	El alias de la cuenta virtual es inválido
`-5088`	`Virtual account has been disabled.`	La cuenta virtual fue deshabilitada
`-5089`	`Virtual account is closed.`	La cuenta virtual está cerrada
`-5090`	`The virtual account is invalid.`	La cuenta virtual es inválida

Errores de órdenes

Los errores de órdenes indican que una operación solicitada sobre una orden no se puede completar debido al estado actual de la orden, a los límites de monto o a una cotización expirada.

Código	`msg`	Significado
`-5008`	`Refund orders cannot be processed`	Las órdenes de reembolso no se pueden procesar
`-5009`	`Order is in payment process and cannot perform current operation`	La orden se está pagando, así que esta operación no está disponible
`-5010`	`Automated orders cannot be completed manually`	Las órdenes automatizadas no se pueden completar manualmente
`-5011`	`Automated orders cannot perform current operation`	Las órdenes automatizadas no admiten esta operación
`-5034`	`The order process is over.`	El proceso de la orden terminó
`-5035`	`Orders cannot be filled at present.`	La orden no se puede ejecutar en este momento
`-5041`	`Only non-payment or support-documents-dending status can upload supporting documents`	Solo se pueden subir documentos de soporte para órdenes no pagadas u órdenes en espera de documentos
`-5050`	`This order does not meet the minimum limit requirement (min {0} {1}).`	La orden está por debajo del monto mínimo (`{0}` `{1}`)
`-5060`	`This order does not meet the maximum limit requirement (max {0} {1}).`	La orden está por encima del monto máximo (`{0}` `{1}`)
`-5200`	`The quotation has expired or is invalid.`	La cotización expiró o es inválida
`-1131`	`Balance insufficient`	Saldo insuficiente. Por ejemplo, una orden de cripto a fiat puede fallar con este código cuando el saldo cripto del comercio es menor que la cantidad de la orden
`-1173`	`Withdraw address illegal.`	La dirección cripto no es válida para la red elegida

Errores de pares de trading

Los errores de pares de trading surgen cuando la combinación solicitada de símbolo, moneda fiat, activo cripto o país no está admitida o está cerrada para operar.

Código	`msg`	Significado
`-5019`	`Invalid trading pair`	Par de trading inválido
`-5020`	`BUY direction is closed`	La compra está cerrada para este par
`-5021`	`SELL direction is closed`	La venta está cerrada para este par
`-5045`	`Invalid fiat`	Moneda fiat inválida
`-5047`	`The symbol does not match the payment method.`	El par no coincide con el método de pago
`-5051`	`Fiat currency in the payment method does not match the order fiat currency`	La moneda fiat del método de pago es distinta a la de la orden
`-5057`	`The currently selected country and fiat currency are not supported.`	El país y la moneda fiat seleccionados no están admitidos
`-5058`	`The currently selected crypto is not supported.`	La cripto seleccionada no está admitida

Errores de control de riesgo

Los errores de control de riesgo indican que la configuración de precios o de tipos de cambio está fuera de los umbrales de seguridad aceptables. Contacta al administrador de tu cuenta de VelaFi para resolver los problemas de configuración.

Código	`msg`	Significado
`-5022`	`Price is below the trade line`	El precio está por debajo del umbral de trading permitido
`-5023`	`The current coin pair is not supported.`	No hay un tipo de cambio configurado para este par, así que no está admitido
`-5024`	`Invalid user rate configuration, please contact the administrator.`	Tu configuración de tipo de cambio es inválida. Contacta a VelaFi
`-5025`	`Invalid risk control rate configuration, please contact the administrator.`	La configuración de tipo de cambio de control de riesgo es inválida. Contacta a VelaFi
`-5027`	`Current exchange rate is invalid.`	El tipo de cambio actual es inválido

Errores de KYC/KYB

Los errores de KYC/KYB indican que un usuario o comercio no ha completado los pasos obligatorios de verificación de identidad o del negocio, o que un proceso de verificación llegó a un estado final.

Código	`msg`	Significado
`-5032`	`Not an OTC whitelist. Please contact the OTC customer service manager if you have any needs.`	Tu cuenta no está en la lista blanca de OTC. Contacta a VelaFi
`-5033`	`You are not yet an API user. Please contact the OTC customer service manager if you have any needs.`	El acceso a la API no está habilitado para tu cuenta. Lo devuelve `GET /v2/token/generate`
`-5037`	`You need to upload supporting documents.`	Se requieren documentos de soporte
`-5042`	`No supporting documents were uploaded`	No se subieron documentos de soporte
`-5043`	`You need to pass KYC & KYB certification first before you can The current operation can be performed.`	Se debe aprobar KYC/KYB antes de realizar esta operación
`-5044`	`You need to pass KYC & KYB certification first before you can add this payment method.`	Se debe aprobar KYC/KYB antes de agregar este método de pago
`-5055`	`KYC & KYB registration failed.`	El registro de KYC/KYB falló
`-5061`	`Has exceeded the maximum number of documents that can be uploaded (maximum {0})`	Se subieron demasiados documentos (máximo `{0}`)
`-5062`	`The merchant's KYC is currently under verification`	El KYC del comercio está en revisión
`-5063`	`The merchant KYC certification process has been end`	El proceso de KYC del comercio terminó

Errores de cumplimiento

Los errores de cumplimiento abarcan una amplia gama de restricciones de políticas y de configuración, incluidos bancos o países no admitidos, límites de transacción excedidos y restricciones de acceso a funciones.

Código	`msg`	Significado
`-5012`	`Bank not supported`	El banco no está admitido
`-5013`	`Automatic API is not supported in this country`	La API automática no está admitida en este país
`-5016`	`The fiat currency does not match with the merchant`	La moneda fiat no coincide con el comercio
`-5026`	`There are currently {0} orders under review, please wait patiently for the result before creating new orders.`	Hay demasiadas órdenes en revisión (`{0}`). Espera a que terminen antes de crear más
`-5028`	`Self-service ordering function is temporarily closed, please try again later.`	La creación de órdenes de autoservicio está cerrada temporalmente
`-5029`	`Order has exceeded user's monthly transaction limit.`	La orden excede el límite mensual de transacciones
`-5030`	`Order has exceeded user's monthly transaction limit with the merchant.`	La orden excede el límite mensual de transacciones para este comercio
`-5081`	`Order has exceeded user's daily transaction limit with the merchant.`	La orden excede el límite diario de transacciones para este comercio
`-5031`	`This transaction is temporarily unavailable. If you have any questions, please contact customer service.`	La transacción no está disponible temporalmente
`-5036`	`fee config invalid. Please contact the OTC customer service manager if you have any needs.`	La configuración de comisiones es inválida. Contacta a VelaFi
`-5046`	`Please try again. If you still have questions, please contact the customer service manager.`	Error genérico. Vuelve a intentarlo o contacta a VelaFi
`-5049`	`Invalid config`	Configuración inválida
`-5052`	`Merchant selection is not available for manual payment methods.`	Los métodos de pago manuales no permiten elegir un comercio
`-5068`	`You are not a user of the Reliance model and therefore cannot use this function.`	Esta función solo está disponible para cuentas del modelo Reliance
`-5072`	`Account type[{0}] doesn’t support the bank code[{1}]`	El tipo de cuenta `{0}` no admite el código de banco `{1}`

Códigos de fallo de órdenes

Estos códigos describen por qué falló una orden después de crearse. Cuando una orden de fiat a cripto o de cripto a fiat falla, Obtener una orden (GET /v2/order/detail) puede reportar uno de ellos en el campo failCode de la orden, con el texto correspondiente en failReason. No todas las órdenes fallidas o canceladas tienen un failCode.

`failCode`	`failReason`	Significado
`-7000`	`Bank order creation failed.`	El banco o el proveedor de pagos no pudo crear el pago
`-7001`	`Incorrect account number for receiving payment.`	El número de la cuenta receptora es incorrecto
`-7002`	`Order cancelled due to timeout.`	La orden se canceló porque se agotó el tiempo
`-7003`	`Order review rejection.`	La orden fue rechazada en revisión
`-7004`	`Order payment is overdue.`	La orden no se pagó a tiempo
`-7005`	`Insufficient account balance and time limit exceeded.`	El saldo siguió siendo insuficiente hasta que venció el tiempo límite
`-7007`	`The receiving bank refused to accept.`	El banco receptor rechazó el pago
`-7100`	El texto de error del propio proveedor	`failReason` contiene el mensaje de error del banco o del proveedor de pagos, que puede ser una cadena JSON

Primeros pasos

Conceptos clave

Guías

Referencia

Códigos de error

Formato de la respuesta de error

Códigos de estado HTTP

Resultado desconocido: verifica antes de reintentar

Errores de autenticación y de solicitud

Errores de parámetros

Errores de métodos de pago

Errores de comercio

Errores de cuentas fiat y cuentas virtuales

Errores de órdenes

Errores de pares de trading

Errores de control de riesgo

Errores de KYC/KYB

Errores de cumplimiento

Códigos de fallo de órdenes

​Formato de la respuesta de error

​Códigos de estado HTTP

​Resultado desconocido: verifica antes de reintentar

​Errores de autenticación y de solicitud

​Errores de parámetros

​Errores de métodos de pago

​Errores de comercio

​Errores de cuentas fiat y cuentas virtuales

​Errores de órdenes

​Errores de pares de trading

​Errores de control de riesgo

​Errores de KYC/KYB

​Errores de cumplimiento

​Códigos de fallo de órdenes

Formato de la respuesta de error

Códigos de estado HTTP

Resultado desconocido: verifica antes de reintentar

Errores de autenticación y de solicitud

Errores de parámetros

Errores de métodos de pago

Errores de comercio

Errores de cuentas fiat y cuentas virtuales

Errores de órdenes

Errores de pares de trading

Errores de control de riesgo

Errores de KYC/KYB

Errores de cumplimiento

Códigos de fallo de órdenes