SDK y API

Catálogo de errores

Referencia de errores del SDK y la API. Cada uno con código, causa típica y cómo remediarlo.

Cómo se ven los errores

El SDK expone clases de error específicas. Podés hacer instanceof para branching preciso:

import {
  WalletNotEnrolledError,
  GAddressNotBootstrappedError,
  WalletAlreadyExistsError,
  RateLimitError,
} from '@accesly/react';

try {
  await tx.swap(args);
} catch (err) {
  if (err instanceof WalletNotEnrolledError) {
    // El SDK auto activa el asset y reintenta
    // Si estás en flow manual, hacé wallet.activateAsset(err.asset)
  }
  if (err instanceof RateLimitError) {
    // Retry después de err.retryAfterSeconds
  }
}

Del lado API REST, todo error viene con esta shape:

{
  "error": "WalletNotEnrolled",
  "code": "WALLET_NOT_ENROLLED",
  "message": "Descriptivo, en español o inglés según Accept-Language",
  "details": { "asset": "USDC" }
}

Errores de autenticación

Clase / código HTTP Causa Remediation
AuthError 401 JWT expirado o inválido Refrescar sesión con auth.signIn o signInWithGoogle
InvalidCredentialsError 401 Email o password mal Pedir al user que corrija
UserNotConfirmedError 403 User signup sin confirmar email Llamar auth.confirmSignUp con el código del email
UserAlreadyExistsError 409 Email ya registrado en Cognito Sugerir login en vez de signup
redirect_mismatch (Cognito) N/A Redirect URI no registrada Agregar URL en Settings del app del dashboard
unauthorized_client (Cognito) N/A OAuth flow no habilitado en Cognito client Contactar soporte Accesly. Bug del setup del app.

Errores de wallet

Clase / código HTTP Causa Remediation
WalletAlreadyExistsError 409 Backend ya tiene wallet para este user pero device no tiene credential local Dispara flow de recovery. El kit lo hace auto en <CreateWalletFlow /> con onRecoverInstead.
WalletNotEnrolledError 409 Rule biometric tx missing para el asset Auto: wallet.activateAsset(err.asset) + retry. El SDK lo hace transparente con withAutoEnroll.
GAddressNotBootstrappedError 409 G address bridge no existe Auto: wallet.bootstrapG(material) + retry.
GMissingTrustlineError 409 G address existe pero sin trustline del asset Auto: wallet.addTrustlineG + retry.
RotateWriteCapExceededError 422 Wallet con 4+ context rules. rotate_signer atómico excede el cap Soroban P27 (132KB writeBytes). Auto: el SDK ejecuta el flow multi tx del Smart Account v3.2.0 (rotate_signer_partial por batches + finalize_rotation). Solo llega al caller si el flow multi tx también falla.
Sin CredentialRecord local N/A IndexedDB vacío. Device nuevo o cache borrado. Recovery flow.
Wallet not on chain N/A Bootstrap disparó POST pero Soroban aún no confirma Poll con useWalletStatus. Puede tardar hasta 30s.

Errores de transacciones

Código Causa Remediation
INSUFFICIENT_FUNDS Balance del user menor que amount + fees Mostrar balance actual, sugerir fondear con on ramp
SPENDING_LIMIT_EXCEEDED Superás el spending limit rule del contract Warning al user, hacerlo esperar el reset del window o reducir monto
PATH_NOT_FOUND Soroswap sin liquidity para el par Auto: fallback a SDEX. El kit lo hace transparente.
SLIPPAGE_EXCEEDED Precio movió más allá del slippage tolerance Recotizar, aumentar slippage o cancelar
tx_bad_seq (Horizon) Sequence number stale Retry, el SDK re fetch el sequence
tx_bad_auth (Horizon) Firma no matchea el signer del source account Suele indicar recovery mal terminada o G address desincronizada. Ver Recovery.
aes/gcm: invalid ghash tag Descifrar F1 o F2 con llave equivocada Indica desync entre backend y local. Trigger recovery.

Errores de recovery

Código Causa Remediation
otp-not-found-or-expired OTP consumido, expirado (10 min) o nunca enviado Pedir OTP nuevo
wrong-code OTP incorrecto Reintentar hasta 5 veces
too-many-attempts 5 intentos fallidos del mismo OTP Esperar TTL y pedir nuevo
invalid-jwt recoveryJwt expirado (5 min) o firma inválida Rehacer verifyOtp
no-wallet-for-email Email no tiene wallet asociada User se equivocó de email o no tiene cuenta. Sugerir signup.
no-wallet-for-current-cognito-user Cognito sub actual no tiene wallet, pero email sí (probable dual user) Usar el mismo provider de auth con el que creó la wallet originalmente
email-hash-mismatch JWT tiene email hash distinto al del usuario actual (posible token reuse) Rehacer flow completo
Passphrase equivocada PBKDF2(passphrase) no descifra F3 Reintentar. Si el user no la recuerda, no hay recovery posible.

Errores de KYC y fiat

Código Causa Remediation
KYC_NOT_STARTED User no completó KYC en Dynerox Dispara <AddFundsFlow />, el kit muestra formulario
KYC_PENDING_IDENTITY User completó datos pero falta liveness Abrir authorizationUrl de Dynerox
KYC_INACTIVE Dynerox rechazó al user (OFAC, mismatch, etc.) Escalación manual con soporte de Dynerox
CLABE_INVALID CLABE mal formada o no reconocida Validar 18 dígitos + banco válido antes de submit
CURP_INVALID CURP no matchea con nombre + fecha de nacimiento Pedir al user que revise sus datos
country-not-supported User no es de México Deshabilitar on ramp UI, sugerir transferencia externa

Errores de rate limit

Clase HTTP Header Remediation
RateLimitError 429 Retry-After: <seconds> Backoff exponencial. El SDK maneja retries auto para GETs idempotentes.

Errores del backend

Clase HTTP Causa Remediation
ServerError 500 Bug en Lambda o dependencia externa (Soroban RPC caído) Retry. Si persiste, revisar /status endpoint.
NetworkError N/A (SDK side) Timeout o CORS Retry con backoff. Verificar conectividad.
ValidationError 400 Body mal formado o campo requerido missing Ver errors array en la response para detalle campo por campo
NotFoundError 404 Recurso no existe Verificar el ID / address / handle

Estrategia general de error handling

Para tu error boundary genérico, cubrí estos casos en este orden:

  1. RateLimitError: mensaje "Muchos intentos, esperá X segundos" con countdown.
  2. AuthError: redirect a login.
  3. WalletAlreadyExistsError: redirect a /recover.
  4. NetworkError: banner "Sin conexión, reintentá".
  5. ServerError: banner "Servicio con problemas, reintentá en un rato".
  6. Default: mensaje del error + link a soporte.

Nunca mostrés stack traces raw al usuario. Loguealos a Sentry o similar y mostrá copy amigable.

Reportar bugs

Si encontrás un error que no está en este catálogo o un mensaje confuso, abrí issue en github.com/Accesly con:

Siguientes pasos