Errores, límites y versionado

Formato de error#

Todos los errores de /api/dex/v1 tienen la misma forma JSON y un código HTTP acorde:

{
  "success": false,
  "error": {
    "schema_version": "botradix-dex-error-v1",
    "code": "SCOPE_NOT_ALLOWED",
    "message": "…",
    "retryable": false,
    "details": {},
    "request_id": "dxr_…"
  },
  "request_id": "dxr_…",
  "api_version": "v1",
  "api_schema_revision": "botradix-dex-api-v1.1"
}

Usa error.code en tu lógica (los mensajes pueden cambiar) y guarda request_id si contactas con soporte. retryable: true indica que la misma petición puede funcionar más tarde.

Errores habituales#

Códigos de la versión 2.2#

Al invertir junto a una posición neta del lado contrario con la misma clave, la respuesta puede devolver el id de esa neta: no hay DexPositionOpened, sino DexPositionChanged de la neta.

Por qué una acción preparada no se puede ejecutar#

Cuando prepare funciona pero execution.ready es false, execution.reason lo explica:

Límites de uso#

Cada clave de API tiene sus propios límites, contados en ventanas de 60 segundos:

Las quotas propias de una clave se pueden fijar al crearla o rotarla, hasta estos máximos por minuto: peticiones 30.000, órdenes 12.000, ráfaga 1.000, lecturas de cuenta 20.000 y lecturas históricas 12.000.

Además de los límites por clave, el borde de red admite hasta 100 peticiones por segundo por IP (ráfagas de 200) y 60 por segundo por clave de API (ráfagas de 120). Esos rechazos son respuestas 429 simples, sin el cuerpo JSON.

Las respuestas incluyen X-RateLimit-Limit, X-RateLimit-Remaining y X-RateLimit-Reset (hora Unix en segundos en la que se reinicia la ventana) para el límite general de la clave. Las respuestas 429 no llevan Retry-After: espera de forma exponencial con algo de aleatoriedad (por ejemplo 1, 2, 4, 8 segundos).

Reintentos#

• Reintenta ante 429, ante 5xx y cuando error.retryable sea true, con espera exponencial.
• Reutiliza la misma clave de idempotencia, con los mismos datos, al reintentar un prepare o un execute, para que una respuesta perdida no cree una segunda preparación ni una segunda orden.
• Nunca reintentes a ciegas una transacción ya enviada: consulta antes /transactions o /native/executions/{tx_hash}.

Cabeceras de respuesta#

Política de versionado#

• /api/dex/v1 es el contrato estable de integración. En v1 se pueden añadir campos y endpoints nuevos sin aviso; tu cliente debe ignorar los campos que no conozca.
• Los cambios que romperían integraciones existentes se publican en una versión nueva.
• GET /meta devuelve la revisión de esquema y las capacidades actuales.
• Los endpoints sin versión que usa el terminal web (/api/dex/… sin v1) pueden cambiar en cualquier momento.