Esta versión (v0.7) todavía no se publicó en npm.
Ir al contenido

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.

ts
if (isEnginexError(e, 'ABORTED') && e.status === 0) return // canceled by the app: ignore

details 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ódigoStatus típicoSignificadoMétodos que lanzan
UNKNOWNcualquieraStatus 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_ERROR500Error interno del gateway.cualquier método
INVALID_ARGUMENT400/422 o 0Pará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_FOUND404Recurso no encontrado.cualquier método
ALREADY_EXISTS409El recurso ya existe (conflicto).cualquier método
PERMISSION_DENIED403Sin permiso para el recurso.cualquier método
UNAUTHENTICATED401Sin 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_EXHAUSTED429Límite de uso alcanzado.resendPhoneVerification, otros con rate limit
FAILED_PRECONDITION412/422Precondición del servidor no satisfecha.cualquier método
ABORTED0 o un status HTTPCancelació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
UNAVAILABLE502/503/504Gateway o dependencia fuera de servicio.cualquier método

Autenticación y cuenta ​

CódigoStatus típicoSignificadoMétodos que lanzan
INVALID_CREDENTIALS401Correo/CPF o contraseña incorrectos.login, changePassword, disable2fa
ACCOUNT_LOCKED403Cuenta bloqueada temporalmente (p. ej., exceso de intentos).login
ACCOUNT_SUSPENDED403Cuenta suspendida por el operador.login
ACCOUNT_BLOCKED403Cuenta bloqueada permanentemente.login
TOKEN_EXPIRED401Access 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_INVALID401Token malformado o revocado; incluye el token de resetPassword/verifyEmail.resetPassword, verifyEmail, requests autenticados
SESSION_EXPIRED401Sesión expirada en el gateway (el refresh token también es inválido).requests autenticados
2FA_REQUIRED428El 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_INVALID422Código 2FA incorrecto o expirado.login, verify2fa, disable2fa

Registro y verificación ​

CódigoStatus típicoSignificadoMétodos que lanzan
USER_NOT_FOUND404Usuario no encontrado.cualquier método con userId
EMAIL_ALREADY_EXISTS409Correo ya registrado.register
CPF_ALREADY_EXISTS409CPF ya registrado.register
INVALID_CPF422CPF inválido (dígito verificador).register
INVALID_EMAIL422Correo inválido.register
INVALID_PHONE422Teléfono inválido.register, requestPhoneChange
PASSWORD_EXPIRED403Contraseña expirada; pide el cambio antes de continuar.login
PASSWORD_SAME_AS_CURRENT422La 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ódigoStatus típicoSignificadodetailsMétodos que lanzan
captcha_required428Captcha obligatorio antes de repetir la llamada.{ site_key: string } (o ausente) — tipado en ErrorDetailsMap como CaptchaRequiredDetails | undefinedlookupCpf
rate_limited429Límite de llamadas a la Receita (autoridad tributaria de Brasil) alcanzado.crudolookupCpf
cpf_already_registered409El CPF ya tiene cuenta.crudolookupCpf
cpf_validation_failed422CPF inválido o no encontrado en la Receita.crudolookupCpf

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ódigoStatus típicoSignificadoMétodos que lanzan
INSUFFICIENT_BALANCE422Saldo insuficiente para la operación.withdrawals.request (sin OTP), withdrawals.confirmOtp
KYC_REQUIRED422Verificación de identidad pendiente para mover dinero.deposits.createPix, withdrawals.request, withdrawals.confirmOtp
WITHDRAWAL_LIMIT_EXCEEDED429Límite de retiro (juego responsable/operador) excedido.withdrawals.request (sin OTP), withdrawals.confirmOtp
DEPOSIT_LIMIT_EXCEEDED429Límite de depósito (juego responsable/operador) excedido.deposits.createPix
WITHDRAWAL_PENDING500Ya existe un retiro pendiente.withdrawals.request (sin OTP), withdrawals.confirmOtp
PAYMENT_FAILED500Pago rechazado por el proveedor.deposits.createPix, withdrawals.request, withdrawals.confirmOtp
PAYMENT_EXPIRED500La ventana de pago expiró (p. ej., PIX).métodos de pago
PAYMENT_CANCELLED500Pago cancelado por el jugador o por el proveedor.métodos de pago
RESERVATION_NOT_FOUND500Reserva de saldo no encontrada (expirada o ya confirmada).productos (apuestas, casino)
RESERVATION_EXPIRED500La reserva de saldo expiró antes de confirmar.productos (apuestas, casino)
DUPLICATE_TRANSACTION500Transacción duplicada en el servicio de billetera.métodos que mueven dinero
TRANSACTION_FAILED500La 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ódigoStatus típicoSignificadoQué hacer
KEY_IN_USE409La 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_MISMATCH422La clave ya se usó con otro cuerpo (otro monto, otra clave PIX).Bug de la app: genera una clave nueva por operación.
INVALID_KEY400Clave de más de 255 caracteres.Usa un UUID (crypto.randomUUID()).

Apuestas deportivas ​

CódigoStatus típicoSignificado
BET_NOT_FOUND404Apuesta no encontrada.
BET_CLOSED422Mercado cerrado para la apuesta.
ODDS_CHANGED409La cuota cambió entre la cotización y la confirmación.
CASHOUT_UNAVAILABLE422Cashout no disponible para esta apuesta.
BET_LIMIT_EXCEEDED422Lí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ódigoStatus típicoSignificadoMétodos que lo lanzan
GAME_NOT_FOUND404Juego no encontrado en el catálogo.casino.getGame, casino.launchGame
SESSION_NOT_FOUND404Sesión de juego (en el proveedor) no encontrada.métodos de sesión del casino
PROVIDER_ERROR503Error en el proveedor de casino: trátalo como no disponible.catálogo y casino.launchGame
CASINO_UNAVAILABLE500Casino 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ódigoStatus típicoSignificadoMétodos que lo lanzan
BONUS_NOT_FOUND404La 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_EXPIRED500Fuera 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_ELIGIBLE500El 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_CLAIMED409Recompensa 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ódigoStatus típicoSignificadoMétodos que lo lanzan
EVENT_NOT_FOUND500Evento no encontrado.markets.getEvent
MARKET_NOT_FOUND500Mercado no encontrado.markets.getMarket y las lecturas del mercado, orders.place, comments.list, comments.create
MARKET_NOT_OPEN500El mercado aún no abrió o ya cerró.orders.place, orders.placeBatch
NO_LIQUIDITY500Sin liquidez para cruzar la orden.orders.place, orders.placeBatch
ORDER_NOT_FOUND500Orden no encontrada (o de otro jugador).orders.get, orders.cancel, orders.amend
COMMENT_NOT_FOUND500Comentario no encontrado.comments.like, comments.unlike

orders.place también lanza INSUFFICIENT_BALANCE (consulta Financiero y pagos).

Compliance y juego responsable ​

CódigoStatus típicoSignificadoMétodos que lanzan
KYC_REQUIRED422Verificación de identidad (KYC) pendiente antes de la operación.endpoints de retiro/depósito (fuera de este SDK)
KYC_PENDING422KYC enviado y en revisión.ídem
KYC_REJECTED500KYC rechazado. El handleAppError del gateway tampoco lo mapea: llega como HTTP 500 con el code preservado.ídem
SELF_EXCLUDED422Jugador en autoexclusión.login, casino.launchGame
COOLING_OFF500Jugador 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ódigoSignificado
NETWORK_ERRORFalla de red (fetch rechazó): DNS, conexión rechazada, CORS bloqueado, sin conexión.
TIMEOUTEl request no respondió dentro de timeoutMs.
ABORTEDLa 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_ERRORRespuesta 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_ERRORConfiguració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.