> 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/errors.md). # Errores Los códigos de estado que declara el contrato, los encabezados de límites de solicitudes y por qué un 401 no te dice nada. Cada página de endpoint generada enumera los estados que declara esa operación. Esta página explica qué significa cada código en toda la API, y los dos lugares en los que el contrato te dice poco a propósito. ## Modelo de errores | Estado | Significado | Notas | | ------ | -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `200` | Éxito | 123 operaciones | | `201` | Creado | 5 operaciones. `POST /orders` y `POST /orders/batch` con sus gemelas `/api/v1`, y `POST /api/v1/bridge/withdrawals`. | | `101` | Cambio de protocolos | Las dos rutas de upgrade de WebSocket | | `400` | Error de validación | 50 operaciones. El cuerpo lleva un `code` legible por máquina cuando el contrato define uno, p. ej. `invalid_window`, `bad_wallet`, `bad_agent`, `expiry_out_of_range`, `invalid_json`. Los rechazos de órdenes cubren margen insuficiente, tick mínimo inválido, órdenes que no se pueden modificar e incumplimiento de margen. | | `401` | Falló la autenticación | 89 operaciones. **Todas las respuestas 401 devuelven el mismo cuerpo opaco, `{"code":"unauthorized"}`, a propósito, para evitar fugas de información.** Un 401 no te dice *por qué*. Una clave incorrecta, una firma incorrecta, una marca de tiempo desactualizada y una sesión vencida se ven igual. Revisa primero el desfase de tu reloj. | | `403` | Prohibido | 25 operaciones. Rechazos por control de jurisdicción en escrituras de órdenes, financiamiento, apalancamiento, margen y retiros por el puente, que son permanentes para el origen de quien llama, así que no reintentes. Los endpoints de administración (requieren el secreto de administrador). `POST /account/credit` cuando un operador congeló las acreditaciones (`credits_frozen`). `EARLY_ACCESS_REQUIRED` en `GET /account/deposit-target`. Retiros rechazados en `POST /withdrawals`. `TRANSFER_ACCOUNT_INELIGIBLE` o `TRANSFER_OUTFLOW_BLOCKED` en las operaciones `/transfers`. | | `404` | No encontrado, o no te pertenece | 26 operaciones. Las fallas de propiedad devuelven 404, no 403, para que no puedas sondear los recursos de otras cuentas. | | `409` | Conflicto | 7 operaciones. `duplicate_agent` en el registro de agentes. Un `client_id` ya tomado por una orden que ya no está en el libro, al enviar una orden. La validación de admisión del ciclo de vida del mercado en una modificación. Una `Idempotency-Key` reutilizada con un monto distinto en `POST /api/v1/bridge/withdrawals`. `TRANSFER_ID_CONFLICT` en `POST /transfers`. | | `422` | No procesable | 1 operación. `POST /account/margin-mode` con datos semánticamente inválidos, campos desconocidos o un `margin_mode` distinto de `cross` o `isolated`. El JSON mal formado es un `400`. | | `426` | Se requiere actualización | 1 operación. `POST /account/deposit` cuando una clave de servicio verificada envía la cuenta acreditada en el encabezado `X-Account-Id`. En su lugar, envía `account_id` en el cuerpo firmado. | | `429` | Límite de solicitudes superado | 74 operaciones. Ver más abajo. | | `500` | Error interno | 3 operaciones. `INTERNAL_ERROR` en `POST /auth/login` cuando falla la escritura en el almacén de sesiones, y un error interno inesperado en `GET` y `POST /account/margin-mode`. | | `502` | Servicio upstream no disponible | 14 operaciones. En `/account/summary` y `/account/state` y sus gemelas `/api/v1`, `authoritative_margin_unavailable`: la vista de margen de referencia del motor no está disponible temporalmente. Los endpoints que derivan saldos de ella **fallan cerrados** y devuelven el error en lugar de una cifra estimada localmente y potencialmente insegura. Es transitorio, así que reintenta después de una breve espera. Los demás son `BAD_GATEWAY` en las lecturas de referidos, `FUNDING_SOURCE_*` en la instantánea de financiamiento, un paso downstream fallido en `POST /api/v1/bridge/withdrawals` y resultados `TRANSFER_*` en las operaciones `/transfers`. | | `503` | Servicio no disponible | 11 operaciones. `DEPOSIT_TARGET_MISCONFIGURED` en `GET /account/deposit-target`, `REFERRAL_STORE_NOT_CONFIGURED` en las lecturas de referidos, `TRANSFERS_UNAVAILABLE` en las operaciones `/transfers`, retiros no disponibles en `POST /api/v1/bridge/withdrawals` y un ajuste de margen que no se pudo registrar de forma duradera en `POST /account/margin`. | Una operación es una ruta y un método en `openapi.json`, y cada gemela `/api/v1` se cuenta por separado. Un conteo es la cantidad de operaciones que declaran ese estado. Para recalcularlos, ejecuta esto desde la raíz del repositorio: ```bash python3 -c 'import json, collections; d = json.load(open("eng/apps/exchange/api/openapi.json")); print(sorted(collections.Counter(code for item in d["paths"].values() for method, op in item.items() if method in ("get", "put", "post", "delete", "patch") for code in op.get("responses", {})).items()))' ``` ### El 429 y los encabezados de límites de solicitudes Un cuerpo `429` se ve como `{"code":"RateLimitExceeded","tier":"Pro"}` y la respuesta lleva: | Encabezado | Significado | | ----------------------- | ---------------------------------------------------- | | `X-RateLimit-Limit` | Solicitudes por segundo permitidas para tu nivel | | `X-RateLimit-Remaining` | Solicitudes restantes en la ventana actual | | `X-RateLimit-Reset` | Marca de tiempo Unix en la que se reinicia el límite | | `Retry-After` | Segundos que hay que esperar antes de reintentar | Regula tu ritmo según los encabezados `X-RateLimit-*` en lugar de reintentar a ciegas. Dos endpoints reutilizan `429` con un significado que no es de límite de solicitudes: `POST /account/credit` (asignación diaria de crédito agotada, se reinicia a la medianoche UTC) y `POST /faucet` (no transcurrió el tiempo de espera o se alcanzó el tope acumulado). Para los topes por nivel y los topes de conexiones, consulta [Límites de solicitudes](https://docs.nexus.xyz/exchange/apis-and-rates/rate-limits). ## Compatibilidad con CCXT ### Soporte de versiones de la API El identificador de versión es el tag publicado de la especificación de este contrato. El edge publica las versiones que acepta en `/metadata`, que sirve el edge y que **no** es una operación de este contrato. Devuelve `current_api_version` (el último tag servido) y `min_api_version` (el tag más antiguo que todavía se acepta), para que los clientes y los agentes puedan leer la ventana de soporte de forma programática. Antes de la 1.0 (`v0.x.y`), los cambios incompatibles son frecuentes y `min_api_version` puede avanzar con cualquier versión incompatible. Un tag publicado sigue teniendo soporte durante al menos **14 días** después de la versión que lo reemplaza, y esa ventana se amplía después de la 1.0. Una solicitud cuyo `X-Nexus-Api-Version` nombra un tag reconocido más antiguo que `min_api_version` recibe un `426 Upgrade Required` legible por máquina (`api_version_unsupported`) con un enlace a la especificación actual, para que las herramientas puedan detectar el desfase y actualizarse. Como el encabezado no está autenticado, esta validación es una ayuda de compatibilidad, no un control de seguridad. Falsificar el valor solo la relaja. Consulta también [Versionado de la API](https://docs.nexus.xyz/exchange/apis-and-rates/api-versioning). --- # 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/errors.md?ask=&goal= ``` `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.