> ## Documentation Index
> Fetch the complete documentation index at: https://docs.velafi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Códigos de error

> Referencia completa de todos los códigos y mensajes de error de la API de VelaFi, organizados por categoría para ayudarte a diagnosticar y resolver rápidamente los problemas de integración.

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`:

```json theme={null}
{
  "code": 200,
  "msg": "SUCCESS",
  "data": { ... }
}
```

> [!NOTE]
>
> Algunos endpoints, entre ellos [Aumentar límite](https://docs.velafi.com/es/api-reference/merchant/upgrade-merchant-limit.md) (`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 theme={null}
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"}
```

**code** `integer`

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

**msg** `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.

**message** `string`

Opcional. Detalle adicional, presente solo en algunos errores.

**fields** `object`

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

> [!NOTE]
>
> 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."}` |

> [!WARNING]
>
> 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

> [!WARNING]
>
> 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](https://docs.velafi.com/es/api-reference/order/retrieve-a-list-of-orders.md) (`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](https://docs.velafi.com/es/api-reference/overview.md#rate-limits). 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](https://docs.velafi.com/es/api-reference/order/retrieve-a-specific-order.md) (`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 |


## Related topics

- [Descripción general de la API](https://docs.velafi.com/es/api-reference/overview.md)
- [Registro de cambios](https://docs.velafi.com/es/docs/changelog.md)
- [Activar la cuenta de un comercio persona física](https://docs.velafi.com/es/api-reference/merchant/activate-merchant-account-for-individual.md)
- [Autenticación](https://docs.velafi.com/es/api-reference/authentication.md)
- [Off-ramp (cripto a fiat)](https://docs.velafi.com/es/docs/guides/off-ramp.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.