Errores

Toda respuesta que no sea 2xx en /v1 usa un único sobre. Base su lógica en errors[0].code, nunca en el texto del mensaje: los mensajes son para personas y pueden cambiar, mientras que los códigos son estables.

El sobre de error

{
  "status": "error",
  "data": null,
  "errors": [
    {
      "code": "IDEMPOTENCY_KEY_CONFLICT",
      "message": "Idempotency-Key was already used with a different request body",
      "parameter": "idempotency-key"
    }
  ]
}

• status es siempre "error" y data es siempre null.
• errors tiene al menos una entrada. code es uno de los valores de la tabla de abajo; parameter nombra el campo o el encabezado causante cuando el error se puede atribuir a uno, y en caso contrario es null.

Identificadores de solicitud

Cada respuesta incluye un encabezado x-request-id. Si envía un x-request-id bien formado con la solicitud, se devuelve tal cual; si no, se genera uno. Regístrelo con cada llamada e indíquelo al contactar con soporte en hello@leeri.ai.

Cómo reaccionar

Situación	Qué hacer
429 con RATE_LIMIT_EXCEEDED o PROVIDER_CAPACITY_EXCEEDED	Espere el número de segundos del encabezado Retry-After y reintente la misma solicitud. Vea Límites de solicitudes y cuotas.
503 con REPORT_RENDERING	Reintente tras el intervalo de Retry-After; el enlace del informe sigue siendo válido.
503 con RULESET_UNAVAILABLE, RATE_LIMIT_STORE_UNAVAILABLE, SERVICE_DRAINING o UPSTREAM_UNAVAILABLE	No se envía Retry-After. Reintente con retroceso exponencial y jitter. No se cobra nada por una solicitud rechazada.
500 con INTERNAL_ERROR	Reintente con retroceso y el mismo Idempotency-Key; si sigue fallando, contacte con soporte con el x-request-id.
409 con IDEMPOTENCY_REQUEST_IN_FLIGHT	La primera solicitud con esta clave sigue en curso. Reintente la misma solicitud tras una breve pausa. Vea Idempotencia.
409 con IDEMPOTENCY_LEASE_LOST	Otro reintento tomó la clave mientras esta solicitud se ejecutaba. Envíe de nuevo la misma solicitud para leer el resultado registrado.
422 con PROVIDER_CAPACITY_REQUEST_TOO_LARGE	No la reintente sin cambios: la solicitud es mayor que la capacidad que se podrá asignar jamás. Divídala en solicitudes más pequeñas.
402 con INSUFFICIENT_BALANCE	La cuota y el saldo prepagado están agotados. Reintentar no sirve hasta que se recargue el saldo.
Cualquier otro 4xx	La solicitud en sí es incorrecta (VALIDATION_ERROR, ADDRESS_REQUIRED, UNSUPPORTED_ASSET, NOT_FOUND, SCOPE_ERROR, etc.). Corríjala; reintentarla sin cambios devuelve el mismo error.

Una solicitud que termina con un estado 4xx o 5xx no se registra bajo su Idempotency-Key, de modo que un reintento se ejecuta de nuevo.

Códigos de error

La tabla se genera a partir del contrato de la API al que está fijada esta documentación, así que siempre lista exactamente los códigos que la API puede devolver. Cada código es un destino de enlace: por ejemplo, ./errors.mdx#ADDRESS_REQUIRED apunta a su fila.

Código	Estado HTTP	Condición
VALIDATION_ERROR	400	El cuerpo de la solicitud, los parámetros o un encabezado no superaron la validación de Zod: un campo desconocido, un valor fuera de sus límites declarados o una estructura que el endpoint no puede interpretar.
AUTH_ERROR	401	El encabezado Authorization falta, está mal formado o no corresponde a una clave de API activa y vigente.
SCOPE_ERROR	403	La clave de API se autenticó, pero no tiene el scope que exige esta ruta.
TENANT_BOUNDARY	403	Una lectura o escritura en la capa de datos detectó una referencia a los datos de otro cliente (tenant): es el rechazo de la propia protección RLS de la plataforma, no una comprobación a nivel de ruta.
NOT_FOUND	404	No existe ningún recurso con este id para el cliente autenticado y el entorno de la clave (live/sandbox). Esto incluye el id de otro cliente o de otro entorno, que se responde deliberadamente igual que un id inexistente.
IDEMPOTENCY_KEY_CONFLICT	422	El mismo Idempotency-Key ya se usó con este endpoint con un cuerpo de solicitud distinto.
INSUFFICIENT_BALANCE	402	El cliente ha agotado tanto la cuota restante como el saldo prepagado del período de facturación actual.
PROVIDER_CAPACITY_EXCEEDED	429	La capacidad global o del cliente para el trabajo con fuentes de datos de terceros está llena. No se acepta ninguna verificación ni reserva de saldo; reintente tras el intervalo indicado en Retry-After. Con el flujo duradero de fuentes, cada verificación live ocupa hasta 10 espacios hasta que sus consultas quedan fijadas; la capacidad predeterminada del cliente es de 1000 espacios, es decir, 100 verificaciones live esperando fuentes a la vez, lo que siempre admite un lote completo de 100 elementos.
PROVIDER_CAPACITY_REQUEST_TOO_LARGE	422	Esta única solicitud necesita más espacios de los que contiene en total la capacidad del cliente o la global, por lo que nunca puede admitirse: reintentar no sirve y no se envía Retry-After. No se acepta ninguna verificación ni reserva de saldo; divida la solicitud en otras más pequeñas.
RULESET_UNAVAILABLE	503	Ningún conjunto de reglas de puntuación publicado estaba accesible al ejecutar la verificación; cuando esto ocurre, la verificación nunca se cobra.
RATE_LIMIT_STORE_UNAVAILABLE	503	El almacén de límites de solicitudes no está accesible. La solicitud se rechaza en lugar de atenderse sin ningún límite (fail-closed).
RATE_LIMIT_EXCEEDED	429	Se superó un límite de solicitudes: por IP, por llamante, de autenticación fallida, el límite por cliente de rederive o de informes de direcciones, o el límite específico de la documentación. Reintente tras la ventana indicada en Retry-After.
SERVICE_DRAINING	503	La instancia se está apagando y rechaza trabajo nuevo; reintente contra otra instancia.
UPSTREAM_UNAVAILABLE	503	Una dependencia que esta solicitud invoca de forma síncrona (la resolución DNS de la URL de un webhook, una consulta a una fuente de datos de terceros) falló o agotó el tiempo de espera.
REPORT_RENDERING	503	El PDF del informe de evidencias se está generando y no estuvo listo dentro del tiempo de espera. Reintente tras el intervalo indicado en Retry-After; el enlace sigue siendo válido.
REPORT_RENDER_FAILED	503	No se pudo generar el PDF del informe de evidencias. El mensaje incluye el identificador corto del informe que debe indicar a soporte; abrir de nuevo el enlace tras una breve pausa reintenta la generación.
UNSUPPORTED_ASSET	422	El símbolo del activo no está en el registro de activos que admite el motor de cribado.
ADDRESS_REQUIRED	422	Una verificación de transacción omitió address para un activo que no puede derivarla (cualquiera salvo TRX, ETH, BNB y BASE), o una clave sandbox la omitió en cualquier verificación de transacción. Envíe la dirección de su cliente en la transacción.
TRANSACTION_UNRESOLVED	422	Una verificación de transacción omitió address y no se pudo leer la transacción de su cadena (no existe esa transacción en esa red, no se puede decodificar el destinatario de un depósito o la fuente de datos de la cadena no respondió a tiempo). No se acepta ni se cobra nada; compruebe el hash y la red, reintente o envíe la dirección.
PAYLOAD_TOO_LARGE	413	El cuerpo de la solicitud supera el límite de tamaño configurado.
IDEMPOTENCY_REQUEST_IN_FLIGHT	409	Otra solicitud con este Idempotency-Key ya se está procesando; reintente en breve.
IDEMPOTENCY_LEASE_LOST	409	Una solicitud de reintento simultánea tomó el arrendamiento de idempotencia de esta solicitud antes de que terminara; reintente para leer el resultado registrado y publicado.
CHECK_FAILED	422	El motor de cribado terminó su ejecución, pero la propia verificación finalizó con un fallo (por ejemplo, un error irrecuperable de una fuente de datos de terceros).
INTERNAL_ERROR	500	Un fallo de servidor sin clasificar. Todo 5xx que esta taxonomía no nombra de otro modo (y todo código puramente interno) se reduce a este; el mensaje original nunca sale del registro del servidor.

El endpoint compatible con AMLBot

El endpoint compatible con AMLBot mantiene la convención de la API que reproduce: responde siempre con HTTP 200 y notifica los fallos en su propio sobre result: false; consulta Respuestas en la guía de migración. El sobre y los códigos de arriba se aplican a /v1.