> For the complete documentation index, see [llms.txt](https://docs.nexus.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.nexus.xyz/api-reference/es-419/guides/known-gaps.md).

# Limitaciones conocidas

Vacíos e inconsistencias del contrato de la API, señalados en lugar de rellenados.

**Esta página es una lista de cosas que el contrato no dice.** Las páginas de endpoints de la sección Referencia se generan a partir de `openapi.json` y describen lo que declara el contrato y nada más. Cuando el contrato guarda silencio, es ambiguo o es inconsistente consigo mismo, esta página lo registra en lugar de rellenar el vacío con una prosa plausible.

Léela antes de construir sobre una operación cuyo comportamiento deduces en lugar de leerlo.

Cada elemento está bajo la parte de la API a la que pertenece. Nada de esto es un compromiso de la hoja de ruta. Son observaciones sobre el contrato tal como está.

**La línea base se verificó contra la especificación `0.9.90`, y cada entrada de abajo se vuelve a comprobar en cada incremento de la especificación** con `.github/scripts/known_gaps_check.py`. Cada entrada registra un predicado contra el contrato en `known-gaps-assertions.json`. Cuando un predicado deja de cumplirse, el vacío se llenó, y la CI falla hasta que se elimine la entrada. Las entradas que afirman algo sobre la prosa y no sobre la estructura están marcadas como verificadas a mano y llevan la versión de la especificación contra la que se leyeron por última vez, que la misma validación exige mantener al día.

Una lista de vacíos desactualizada es peor que no tener ninguna. Entre `0.9.27` y `0.9.63` esta se desactualizó. Ocho entradas estaban mal, y tres de ellas describían vacíos que el contrato ya había cerrado. Por eso la verificación ahora es mecánica y no una promesa de volver a leer.

## Trading

* **Límites de los lotes.** No se declara una longitud máxima de lote para `POST /orders/batch`, y el contrato no dice cómo se pondera un lote frente al límite de solicitudes (una solicitud o una por elemento).
* **`reduce_only`.** Declarado como booleano sin descripción. No se especifica su interacción con los tipos de órdenes condicionales y trailing.
* **Semántica de los campos de `PreviewResponse`.** Los ocho campos tienen tipo, pero no tienen descripciones en el contrato.
* **Dirección del disparador.** "Adversa" y "favorable" no están definidas formalmente por `side` para las familias Stop y Take profit.
* **Vigencia × tipos condicionales.** El contrato no indica qué valores de `time_in_force` son válidos para los seis tipos de órdenes condicionales (por ejemplo, `PostOnly` en un `StopMarket`).
* **Posibilidad de modificación.** Más allá de "las órdenes de liquidación no se pueden modificar", el contrato no dice si las órdenes condicionales o trailing se pueden modificar, ni si una modificación puede cambiar `time_in_force`.
* **Eliminación de `stop_price`.** Marcado como deprecado sin una versión ni una fecha de eliminación indicadas.

## Posiciones

* **Hoy `leverage` es permanentemente `null`.** El contrato indica que es "actualmente siempre `null`" con `leverage_error: "margin_state_not_mirrored"`, y no da ningún plazo para completarlo. Los clientes no pueden leer el apalancamiento por posición en estos endpoints.
* **No hay filtro por mercado en las posiciones cerradas.** `GET /positions/closed` solo acepta `limit` y `cursor`, así que no hay forma de limitar la consulta a un solo mercado. No acepta ni `market_id` ni `symbol`. El campo de la respuesta se renombró a `symbol` en `0.9.74`, y el parámetro nunca existió con ninguno de los dos nombres.
* **Ventana de retención no indicada.** `funding_paid` está documentado como "limitado por el historial de financiamiento que retiene el indexador", pero no se indica ningún período de retención. La paginación por cursor en estos endpoints ya no forma parte de este vacío: `GET /positions/closed` documenta una ventana retenida de 200 registros en `limit`.
* **Falta el `429` en las posiciones cerradas.** `GET /positions/closed` y su gemela `/api/v1` solo declaran `200` y `401`. El contrato omite la respuesta `429` que declara la otra operación de posiciones, aunque se aplica la misma capa de límites de solicitudes.
* **Solo margen cruzado.** `initialMargin` se define "según el modelo de margen cruzado del motor", y el contrato señala que el indexador no replica las asignaciones de margen aislado/personalizado. Así que aquí no se puede leer la asignación real de una posición con margen aislado.
* **No hay conteo ni total de posiciones abiertas.** La respuesta es un arreglo simple sin envoltorio y sin paginación en `GET /positions`, así que no hay un límite documentado de cuántas posiciones puede llevar una sola respuesta.

## Cuenta

* **`direction` no está enumerado.** `POST /account/margin` no declara ningún esquema de solicitud. Su ejemplo muestra `"direction": "add"`, y el resumen y la descripción del `400` implican que también se puede quitar margen, pero el contrato nunca indica el valor para quitarlo. Tampoco nombra los tipos de los campos ni marca ningún campo como obligatorio.
* **Dos operaciones no declaran esquema de solicitud.** `POST /account/deposit` y `POST /account/margin` solo tienen ejemplos de solicitud, así que los clientes generados a partir del contrato reciben cuerpos de solicitud sin tipo para ambas. Sus respuestas sí tienen tipo (`DepositResponse`, `AdjustMarginResponse`); lo que no está declarado es el lado de la solicitud.
* **Dos rutas de depósito superpuestas.** `POST /account/deposit` y `POST /deposits` depositan colateral y devuelven `DepositResponse`, y el contrato no dice cuál preferir ni en qué difieren operativamente. Como las respuestas coinciden, la forma devuelta no permite distinguirlas.
* **Los vocabularios de estado no coinciden.** `Withdrawal.status` es `pending` / `settled` / `failed`, y `FundsEntry.status` es `pending` / `submitted` / `confirmed` / `failed`. El mismo ciclo de vida tiene dos conjuntos de nombres y una cantidad distinta de etapas, así que no existe una correspondencia completa entre ellos. `submitted` no tiene equivalente en `Withdrawal`, y `settled` no tiene ninguno en `FundsEntry`.
* **Las mayúsculas del nivel de límites de solicitudes son inconsistentes.** `RateLimitStatus.tier` está documentado en minúsculas (`pro`, `marketmaker`, `unlimited`). El ejemplo del cuerpo del `429` devuelve `"tier": "Pro"`. Las operaciones de administración de niveles usan `MarketMaker` y `Pro`. El contrato no indica una forma canónica.
* **La cobertura del `429` es desigual.** Varias operaciones sujetas a la misma capa de límites de solicitudes solo declaran `200` y `401`: las dos operaciones de historial de patrimonio, las dos de historial de órdenes, los dos GET y PUT de cancelación al desconectar, `GET /withdrawals`, `GET /deposits`, `POST /deposits`, `GET /orders/{order_id}` y las dos operaciones de estado de límites de solicitudes.
* **Las ventanas de retención son una cantidad de registros, no una duración.** Cada operación ahora indica el tamaño de su ventana retenida (1,000 ejecuciones, 500 registros de historial de órdenes, 200 posiciones cerradas, 720 puntos de patrimonio, 10,000 operaciones). Ninguna operación dice cuánto tiempo atrás abarca eso, así que un cliente no puede saber si un recorrido cubre una semana o un año. El subconteo de `volume_30d` ya no forma parte de este vacío: `volume_30d_estimated` indica qué garantía se aplica.
* **Los máximos de `limit` son menores que lo que dice la prosa en dos lugares.** `GET /withdrawals` y `GET /deposits` limitan `limit` a 100 con un valor predeterminado de 100, así que el parámetro solo puede reducir la página. No hay forma de paginar más allá de 100 registros, porque ninguna de las dos operaciones acepta un `cursor`.
* **`EquityPoint.equity` es un número JSON.** Todos los demás campos monetarios de esta etiqueta son cadenas decimales sin pérdida. El propio contrato señala la diferencia con `PortfolioPoint.equity` e indica a los clientes que comparen por valor decimal, pero la representación como float sigue en el wire.
* **`early_access_allowed` está presente o ausente, no es verdadero o falso.** El contrato dice que aparece "solo cuando la validación de acceso anticipado está activa" sin indicar qué rige la validación ni qué significa su ausencia para quien llama.
* **No hay nivel ni programa de descuentos por cuenta.** `AccountFees.tier` siempre es `base`, `discounts` siempre está vacío y `FeeDiscount` no tiene propiedades definidas. Las comisiones efectivas por mercado para los mercados del búfer de ejecuciones retenido actualmente se entregan en `markets`. La ausencia de un mercado no dice nada sobre la actividad histórica de la cuenta. Quienes llaman deben seguir tratando `schedule` como una cadena abierta y distinguir `per_market`, `reference` y el centinela `unknown` con valor cero.
* **Hoy `Position.leverage` es permanentemente `null`** en cada respuesta que incluye una posición (`AccountSummary`, `AccountState`), con `leverage_error: "margin_state_not_mirrored"`. Consulta [`GET /positions`](https://docs.nexus.xyz/api-reference/positions/fetch-positions).

## Administración

* **Los nombres de los niveles no están enumerados.** No hay esquema, ni `enum`, ni lista. Aquí solo aparece `MarketMaker` como ejemplo, y `pro` / `marketmaker` / `unlimited` aparecen solo en la prosa de la descripción de `RateLimitStatus`. Un operador no puede conocer el conjunto válido a partir del contrato.
* **Las mayúsculas son inconsistentes en todo el contrato.** Estas operaciones usan `MarketMaker` y `Pro`. `RateLimitStatus.tier` está documentado en minúsculas (`pro`, `marketmaker`, `unlimited`). El ejemplo compartido del cuerpo del `429` devuelve `"tier": "Pro"`. El contrato no indica qué forma es la canónica ni si la comparación distingue entre mayúsculas y minúsculas.
* **No hay esquemas de solicitud, y una respuesta no tiene ninguno.** Ninguna de las tres operaciones declara un esquema de solicitud, así que los clientes generados a partir del contrato reciben cuerpos de solicitud sin tipo en todas. `GET` y `PUT /admin/tiers` sí declaran esquemas de respuesta `200`, y `DELETE /admin/tiers/{address}` no.
* **`404 Address not in allowlist` al eliminar, pero ninguna allowlist en otro lugar.** `DELETE /admin/tiers/{address}` devuelve `404` cuando la dirección "no está en la allowlist", mientras que `PUT /admin/tiers` no documenta ninguna precondición de allowlist y `GET /admin/tiers` describe su resultado como "overrides". No se indica la relación entre el almacén de overrides y una allowlist.
* **No se declara ningún `401` ni límite de solicitudes.** Estas operaciones solo declaran `200`, `403` y (al eliminar) `404`. No hay un comportamiento documentado para un encabezado `Authorization` mal formado distinto de un secreto incorrecto, ni una respuesta de límite de solicitudes, así que un secreto bearer no tiene una limitación de frecuencia declarada.
* **No hay registro de auditoría en la superficie.** Nada en el contrato expone quién definió un nivel ni cuándo. `GET /admin/tiers` solo devuelve el estado actual.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.nexus.xyz/api-reference/es-419/guides/known-gaps.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.