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
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:
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:
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.
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.
Última actualización