Códigos de error
Referencia de todo code que un EnginexError puede traer: los del gateway (GATEWAY_ERROR_CODES) y los que el propio SDK genera sin respuesta HTTP (SDK_ERROR_CODES). Consulta Errores para el formato completo de EnginexError y cómo manejarlo.
Sobre las mayúsculas y minúsculas: la mayoría de los códigos del gateway son SCREAMING_SNAKE_CASE, pero algunos endpoints más nuevos (lookupCpf) reflejan el gateway en snake_case minúscula (p. ej., captcha_required). El SDK nunca normaliza las mayúsculas de code — trata la cadena exactamente como la muestra la tabla.
ABORTED aparece en las dos listas (GATEWAY_ERROR_CODES y SDK_ERROR_CODES): el status dice quién lo generó. status: 0 es el SDK — la propia app canceló el request vía signal, y normalmente se puede ignorar; un status distinto de 0 es el gateway, respondiendo con un error de negocio ABORTED (transacción abortada en el servidor), no una cancelación.
if (isEnginexError(e, 'ABORTED') && e.status === 0) return // canceled by the app: ignoredetails viene crudo del gateway (claves como llegaron por la red, sin camelCase) y es unknown por defecto. Solo los códigos con details documentado abajo tienen entrada en ErrorDetailsMap — para ellos, isEnginexError(e, code) estrecha e.details automáticamente (consulta details tipado); para los demás, haz tu propia verificación antes de usar el contenido.
Genéricos del protocolo
Sin un código de negocio específico, el gateway cae en uno de estos según el status HTTP.
| Código | Status típico | Significado | Métodos que lanzan |
|---|---|---|---|
UNKNOWN | cualquiera | Status sin mapeo conocido, o error no reconocido por el SDK (p. ej., EnginexError.from con un valor sin code/message). Con status 2xx: operación no confirmada, vuelve a leer el estado antes de intentar de nuevo (Errores de compliance). | cualquier método; 2xx en kyc.uploadDocument y loyalty.redeem |
INTERNAL_ERROR | 500 | Error interno del gateway. | cualquier método |
INVALID_ARGUMENT | 400/422 o 0 | Parámetros inválidos en el request. Con status: 0, el propio SDK lo rechazó antes de enviar: un id . o .. en la ruta (p. ej., deposits.get({ depositId: '..' })), que la URL normalizaría hacia otra ruta. | register, resetPassword, verifyPhone, confirmPhoneChange, config.get, métodos con id en la ruta, otros |
NOT_FOUND | 404 | Recurso no encontrado. | cualquier método |
ALREADY_EXISTS | 409 | El recurso ya existe (conflicto). | cualquier método |
PERMISSION_DENIED | 403 | Sin permiso para el recurso. | cualquier método |
UNAUTHENTICATED | 401 | Sin sesión válida; también lo lanza el propio SDK antes de enviar (sin llamar a la red) cuando se llama a un método auth: 'required' sin sesión. | changePassword, requestPhoneChange, confirmPhoneChange, enable2fa, verify2fa, disable2fa, otros con sesión obligatoria |
RESOURCE_EXHAUSTED | 429 | Límite de uso alcanzado. | resendPhoneVerification, otros con rate limit |
FAILED_PRECONDITION | 412/422 | Precondición del servidor no satisfecha. | cualquier método |
ABORTED | 0 o un status HTTP | Cancelación: con status: 0, la propia app canceló el request vía signal (normalmente se puede ignorar); el gateway también puede emitir ABORTED con un status HTTP — en ese caso es un error de negocio del servidor, no una cancelación. | cualquier método (SDK, vía signal), o el gateway |
UNAVAILABLE | 502/503/504 | Gateway o dependencia fuera de servicio. | cualquier método |
Autenticación y cuenta
| Código | Status típico | Significado | Métodos que lanzan |
|---|---|---|---|
INVALID_CREDENTIALS | 401 | Correo/CPF o contraseña incorrectos. | login, changePassword, disable2fa |
ACCOUNT_LOCKED | 403 | Cuenta bloqueada temporalmente (p. ej., exceso de intentos). | login |
ACCOUNT_SUSPENDED | 403 | Cuenta suspendida por el operador. | login |
ACCOUNT_BLOCKED | 403 | Cuenta bloqueada permanentemente. | login |
TOKEN_EXPIRED | 401 | Access token expirado; el SDK intenta renovarlo vía refresh automáticamente antes de pasarle esto a la app. | requests autenticados (raro que llegue a la app) |
TOKEN_INVALID | 401 | Token malformado o revocado; incluye el token de resetPassword/verifyEmail. | resetPassword, verifyEmail, requests autenticados |
SESSION_EXPIRED | 401 | Sesión expirada en el gateway (el refresh token también es inválido). | requests autenticados |
2FA_REQUIRED | 428 | El inicio de sesión exige el código de la app autenticadora; el SDK nunca pasa esto como rechazo — login devuelve { status: '2fa_required' }. | manejado internamente por login |
2FA_INVALID | 422 | Código 2FA incorrecto o expirado. | login, verify2fa, disable2fa |
Registro y verificación
| Código | Status típico | Significado | Métodos que lanzan |
|---|---|---|---|
USER_NOT_FOUND | 404 | Usuario no encontrado. | cualquier método con userId |
EMAIL_ALREADY_EXISTS | 409 | Correo ya registrado. | register |
CPF_ALREADY_EXISTS | 409 | CPF ya registrado. | register |
INVALID_CPF | 422 | CPF inválido (dígito verificador). | register |
INVALID_EMAIL | 422 | Correo inválido. | register |
INVALID_PHONE | 422 | Teléfono inválido. | register, requestPhoneChange |
PASSWORD_EXPIRED | 403 | Contraseña expirada; pide el cambio antes de continuar. | login |
PASSWORD_SAME_AS_CURRENT | 422 | La nueva contraseña es igual a la actual. | changePassword |
CPF y captcha (mayúsculas y minúsculas mezcladas, refleja el gateway)
Estos cuatro vienen en snake_case minúscula — no son SCREAMING_SNAKE_CASE como el resto de la lista.
| Código | Status típico | Significado | details | Métodos que lanzan |
|---|---|---|---|---|
captcha_required | 428 | Captcha obligatorio antes de repetir la llamada. | { site_key: string } (o ausente) — tipado en ErrorDetailsMap como CaptchaRequiredDetails | undefined | lookupCpf |
rate_limited | 429 | Límite de llamadas a la Receita (autoridad tributaria de Brasil) alcanzado. | crudo | lookupCpf |
cpf_already_registered | 409 | El CPF ya tiene cuenta. | crudo | lookupCpf |
cpf_validation_failed | 422 | CPF inválido o no encontrado en la Receita. | crudo | lookupCpf |
Financiero y pagos
Pasados por el gateway desde el servicio de pagos/billetera. El status es el que el handleAppError del gateway asigna: los códigos sin categoría propia allí salen como 500, aunque sean errores de negocio — manéjalos por el code, nunca por el status. Los límites mínimo/máximo de depósito y retiro de la config no usan estos códigos: el gateway los rechaza antes, con INVALID_ARGUMENT (400) y un mensaje ya listo (p. ej., depósito mínimo é 10.00 BRL).
| Código | Status típico | Significado | Métodos que lanzan |
|---|---|---|---|
INSUFFICIENT_BALANCE | 422 | Saldo insuficiente para la operación. | withdrawals.request (sin OTP), withdrawals.confirmOtp |
KYC_REQUIRED | 422 | Verificación de identidad pendiente para mover dinero. | deposits.createPix, withdrawals.request, withdrawals.confirmOtp |
WITHDRAWAL_LIMIT_EXCEEDED | 429 | Límite de retiro (juego responsable/operador) excedido. | withdrawals.request (sin OTP), withdrawals.confirmOtp |
DEPOSIT_LIMIT_EXCEEDED | 429 | Límite de depósito (juego responsable/operador) excedido. | deposits.createPix |
WITHDRAWAL_PENDING | 500 | Ya existe un retiro pendiente. | withdrawals.request (sin OTP), withdrawals.confirmOtp |
PAYMENT_FAILED | 500 | Pago rechazado por el proveedor. | deposits.createPix, withdrawals.request, withdrawals.confirmOtp |
PAYMENT_EXPIRED | 500 | La ventana de pago expiró (p. ej., PIX). | métodos de pago |
PAYMENT_CANCELLED | 500 | Pago cancelado por el jugador o por el proveedor. | métodos de pago |
RESERVATION_NOT_FOUND | 500 | Reserva de saldo no encontrada (expirada o ya confirmada). | productos (apuestas, casino) |
RESERVATION_EXPIRED | 500 | La reserva de saldo expiró antes de confirmar. | productos (apuestas, casino) |
DUPLICATE_TRANSACTION | 500 | Transacción duplicada en el servicio de billetera. | métodos que mueven dinero |
TRANSACTION_FAILED | 500 | La transacción falló en el servicio de billetera. | métodos que mueven dinero |
Idempotencia
Emitidos por el middleware de idempotencia del gateway en las rutas que mueven dinero (deposits.createPix, withdrawals.request, withdrawals.confirmOtp, y las de producto). Consulta Idempotencia.
| Código | Status típico | Significado | Qué hacer |
|---|---|---|---|
KEY_IN_USE | 409 | La misma Idempotency-Key todavía se está procesando (otra pestaña, doble clic). | Espera y repite con la misma clave: recibes la respuesta de la primera. |
PAYLOAD_MISMATCH | 422 | La clave ya se usó con otro cuerpo (otro monto, otra clave PIX). | Bug de la app: genera una clave nueva por operación. |
INVALID_KEY | 400 | Clave de más de 255 caracteres. | Usa un UUID (crypto.randomUUID()). |
Apuestas deportivas
| Código | Status típico | Significado |
|---|---|---|
BET_NOT_FOUND | 404 | Apuesta no encontrada. |
BET_CLOSED | 422 | Mercado cerrado para la apuesta. |
ODDS_CHANGED | 409 | La cuota cambió entre la cotización y la confirmación. |
CASHOUT_UNAVAILABLE | 422 | Cashout no disponible para esta apuesta. |
BET_LIMIT_EXCEEDED | 422 | Límite de apuesta del operador excedido. |
Ningún método del SDK los lanza hoy: el sportsbook (FIRST) corre en su propio marco (consulta Sportsbook (FIRST)). Se listan porque el gateway los define.
Casino
Los lanza igaming.casino (Casino y abrir un juego). El gateway no asigna un status propio a todos los códigos: decide por el code.
| Código | Status típico | Significado | Métodos que lo lanzan |
|---|---|---|---|
GAME_NOT_FOUND | 404 | Juego no encontrado en el catálogo. | casino.getGame, casino.launchGame |
SESSION_NOT_FOUND | 404 | Sesión de juego (en el proveedor) no encontrada. | métodos de sesión del casino |
PROVIDER_ERROR | 503 | Error en el proveedor de casino: trátalo como no disponible. | catálogo y casino.launchGame |
CASINO_UNAVAILABLE | 500 | Casino no disponible (proveedor u operador): trátalo como no disponible. | catálogo y casino.launchGame |
casino.launchGame también lanza SELF_EXCLUDED y COOLING_OFF (consulta Compliance y juego responsable).
Bonos
Los lanza igaming.bonus (Bonos y promo codes).
| Código | Status típico | Significado | Métodos que lo lanzan |
|---|---|---|---|
BONUS_NOT_FOUND | 404 | La campaña, la participación o el promo code no existe (o es de otro jugador). | bonus.getOffer, bonus.optIn, bonus.claim, bonus.resolvePromoCode, bonus.redeemPromoCode |
BONUS_EXPIRED | 500 | Fuera de la ventana de entrada o de canje. El gateway aún no lo asigna: decide por el code. | bonus.optIn, bonus.claim, promo codes |
BONUS_NOT_ELIGIBLE | 500 | El jugador no puede participar ni canjear (p. ej., aún no califica). El gateway aún no lo asigna: decide por el code. | bonus.optIn, bonus.claim, promo codes |
BONUS_ALREADY_CLAIMED | 409 | Recompensa ya canjeada; promo code ya usado. | bonus.optIn, bonus.claim, bonus.redeemPromoCode |
Predictions
Los lanza @getenginex/sdk-predictions. El gateway aún no asigna a estos códigos un status propio: llegan con HTTP 500. Decide siempre por el code (Órdenes).
| Código | Status típico | Significado | Métodos que lo lanzan |
|---|---|---|---|
EVENT_NOT_FOUND | 500 | Evento no encontrado. | markets.getEvent |
MARKET_NOT_FOUND | 500 | Mercado no encontrado. | markets.getMarket y las lecturas del mercado, orders.place, comments.list, comments.create |
MARKET_NOT_OPEN | 500 | El mercado aún no abrió o ya cerró. | orders.place, orders.placeBatch |
NO_LIQUIDITY | 500 | Sin liquidez para cruzar la orden. | orders.place, orders.placeBatch |
ORDER_NOT_FOUND | 500 | Orden no encontrada (o de otro jugador). | orders.get, orders.cancel, orders.amend |
COMMENT_NOT_FOUND | 500 | Comentario no encontrado. | comments.like, comments.unlike |
orders.place también lanza INSUFFICIENT_BALANCE (consulta Financiero y pagos).
Compliance y juego responsable
| Código | Status típico | Significado | Métodos que lanzan |
|---|---|---|---|
KYC_REQUIRED | 422 | Verificación de identidad (KYC) pendiente antes de la operación. | endpoints de retiro/depósito (fuera de este SDK) |
KYC_PENDING | 422 | KYC enviado y en revisión. | ídem |
KYC_REJECTED | 500 | KYC rechazado. El handleAppError del gateway tampoco lo mapea: llega como HTTP 500 con el code preservado. | ídem |
SELF_EXCLUDED | 422 | Jugador en autoexclusión. | login, casino.launchGame |
COOLING_OFF | 500 | Jugador en período de cooling-off. El handleAppError del gateway no mapea este código: llega como HTTP 500 con el code preservado. | abrir un juego (casino); decide por code |
Códigos del SDK (sin respuesta HTTP del gateway)
status es siempre 0 en estos — no hubo respuesta HTTP.
| Código | Significado |
|---|---|
NETWORK_ERROR | Falla de red (fetch rechazó): DNS, conexión rechazada, CORS bloqueado, sin conexión. |
TIMEOUT | El request no respondió dentro de timeoutMs. |
ABORTED | La propia app canceló el request vía signal (AbortController). Es el mismo código que el gateway puede emitir con un status HTTP — consulta la tabla Genéricos del protocolo. |
VALIDATION_ERROR | Respuesta del gateway fuera del schema esperado, en modo 'strict' (o, en 'warn', con la propia raíz fuera del formato; consulta Validación de respuestas); o una respuesta 2xx que pasó el schema pero falló una verificación posterior a la respuesta (p. ej., un login sin 2FA que volvió sin tokens). |
CONFIGURATION_ERROR | Configuración del cliente incompleta o ausente: baseUrl/tenantHost/fetch no resueltos (consulta Next.js / SSR); o el cliente se descartó con client.dispose(). |
Códigos nuevos que el SDK aún no conoce
EnginexErrorCode acepta cualquier cadena (KnownErrorCode | (string & {})), así que isEnginexError funciona también para códigos nuevos que el gateway llegue a emitir antes de que el SDK los conozca — el autocompletado sugiere los códigos de arriba, pero no impide otros.