Troubleshooting

Solutions for common issues when building with YaniPay SDK.

Guide de Dépannage

Ce guide vous aide à résoudre rapidement les problèmes courants rencontrés lors de l'intégration du SDK YaniPay. Chaque erreur est accompagnée de sa cause probable et de solutions concrètes testées par notre équipe.

Dans l'écosystème DeFi, les erreurs peuvent avoir des conséquences financières. C'est pourquoi YaniPay met un accent particulier sur des messages d'erreur clairs et des outils de debug avancéspour identifier et corriger les problèmes avant qu'ils n'impactent vos utilisateurs.

Support Prioritaire

Les développeurs avec un plan Enterprise bénéficient d'un support prioritaire avec un temps de réponse garanti de 2h. Contactez support@yanipay.com pour toute question critique.

Cas d'Utilisation

MarcJunior Developer

Rencontre l'erreur "API key not found" lors de son premier déploiement en production.

✓ Problème résolu en 5 minutes grâce à la checklist de configuration

SophieFull Stack Developer

Debug une transaction qui échoue silencieusement en production sans message d'erreur clair.

✓ Identifie le problème de slippage grâce aux logs de simulation

LucasSupport Technique

Aide un utilisateur qui ne peut pas connecter son wallet MetaMask à l'application.

✓ Résolution rapide avec la checklist de connexion wallet

EmmaQA Engineer

Reproduit et documente un bug de rate limiting qui apparaît sous forte charge.

✓ Bug reproduit et fixé grâce aux outils de debug

Flux de Gestion d'Erreur

Voici comment les erreurs sont propagées et gérées dans l'architecture YaniPay :

Toujours Catch les Erreurs

Encapsulez toujours vos appels SDK dans un try/catch et gérez les erreurs de type YaniPayError pour afficher des messages utilisateur appropriés.

Common Errors

"API key not found" or "Invalid API key"

Cause: The API key is not configured or is incorrect.

Solution:

Check that NEXT_PUBLIC_YANIPAY_API_KEY is set in .env.local
Restart your development server after adding the variable
Verify the key is correct in your YaniPay dashboard

.env.localbash

# Make sure this is set correctly
NEXT_PUBLIC_YANIPAY_API_KEY=your_actual_api_key_here

"Module not found: Cannot find module '@/lib/api/client'"

Cause: L'alias de chemin @/ n'est pas résolu, ou le fichier n'existe pas.

Solution:

# Réinstaller les dépendances
rm -rf node_modules pnpm-lock.yaml
pnpm install

# Vérifier les dépendances installées
pnpm list

# Vérifier les types TypeScript
pnpm type-check

"SessionProvider not found in context" / "useSession must be wrapped in SessionProvider"

Cause: Un composant client utilise useSession() en dehors du SessionProvider.

Solution: Vérifier que SessionProvider et CartProvider enveloppent toute l'application dans app/layout.tsx :

app/layout.tsxtsx

import { SessionProvider } from 'next-auth/react';
import { CartProvider } from '@/components/CartProvider';

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        <SessionProvider>
          <CartProvider>
            {children}  {/* Tous les composants doivent être à l'intérieur */}
          </CartProvider>
        </SessionProvider>
      </body>
    </html>
  );
}

Wallet Connection Issues

"Failed to connect wallet"

Check browser extension

Ensure MetaMask or your wallet extension is installed and unlocked.

Check network

Make sure your wallet is connected to the correct network (mainnet or testnet).

Clear cache

Try disconnecting and reconnecting the wallet, or clearing browser cache.

"User rejected the request"

This means the user closed the wallet popup without confirming. Handle this gracefully:

try {
  await connect();
} catch (err) {
  if (err.code === 4001) {
    // User rejected - don't show error, just reset UI
    setConnecting(false);
  } else {
    // Actual error
    setError(err.message);
  }
}

Transaction Errors

"Insufficient balance"

Cause: Not enough tokens or gas.

Solution:

Check token balance before submitting transaction
Ensure wallet has enough native tokens for gas fees
Account for potential slippage when checking balance

// Check balance before swap
const balance = await yanipay.getBalance(tokenIn);
const requiredAmount = parseFloat(amountIn) * 1.005; // Include 0.5% buffer

if (parseFloat(balance) < requiredAmount) {
  throw new Error(`Insufficient ${tokenIn} balance. Need ${requiredAmount}, have ${balance}`);
}

"Transaction reverted"

Common causes:

Slippage too low for volatile markets
Transaction deadline expired
Insufficient liquidity in pool

// Increase slippage for volatile pairs
const swapParams = {
  ...params,
  slippage: '1.0', // Try 1% instead of 0.5%
  deadline: Date.now() + 30 * 60 * 1000, // 30 minute deadline
};

API Errors

Rate Limiting (429 Too Many Requests)

Solution: Implement request caching and debouncing.

import { useState, useEffect } from 'react';
import { useDebounce } from 'use-debounce';

function useCachedPrice(symbol: string) {
  const [price, setPrice] = useState(null);
  const [debouncedSymbol] = useDebounce(symbol, 500);

  useEffect(() => {
    // Check cache first
    const cached = localStorage.getItem(`price_${debouncedSymbol}`);
    if (cached) {
      const { value, timestamp } = JSON.parse(cached);
      if (Date.now() - timestamp < 30000) { // 30 second cache
        setPrice(value);
        return;
      }
    }

    // Fetch fresh data
    fetchPrice(debouncedSymbol).then((p) => {
      setPrice(p);
      localStorage.setItem(`price_${debouncedSymbol}`, JSON.stringify({
        value: p,
        timestamp: Date.now(),
      }));
    });
  }, [debouncedSymbol]);

  return price;
}

Network Errors

Solution: Implement retry logic with exponential backoff.

async function fetchWithRetry(url: string, maxRetries = 3) {
  let lastError;

  for (let i = 0; i < maxRetries; i++) {
    try {
      const response = await fetch(url);
      if (response.ok) return response.json();
      if (response.status < 500) throw new Error(await response.text());
    } catch (err) {
      lastError = err;
      // Exponential backoff: 1s, 2s, 4s
      await new Promise(r => setTimeout(r, 1000 * Math.pow(2, i)));
    }
  }

  throw lastError;
}

Debugging Tips

Mode Debug en Production

Ne laissez JAMAIS le mode debug activé en production ! Les logs peuvent exposer des informations sensibles comme les balances utilisateur ou les paramètres de transaction.

Enable Debug Mode

const yanipay = new YaniPay({
  apiKey: process.env.NEXT_PUBLIC_YANIPAY_API_KEY!,
  logging: {
    level: 'debug', // Shows all internal operations
    prefix: '[YaniPay]',
  },
});

Inspect Network Requests

Use browser DevTools (Network tab) to inspect API requests and responses. Look for:

Request URL and parameters
Response status codes
Response body for error messages

Check Transaction on Explorer

If a transaction fails, find it on the block explorer for more details:

try {
  const result = await yanipay.swap(params);
  console.log(`Success: https://explorer.yanichain.com/tx/${result.hash}`);
} catch (err) {
  if (err.transactionHash) {
    console.log(`Failed TX: https://explorer.yanichain.com/tx/${err.transactionHash}`);
  }
}

Getting Help

Discord Community

Join our Discord for real-time help from the community

GitHub Issues

Report bugs or request features on GitHub

When Reporting Issues

Include the following information:

Versions des dépendances (pnpm list)
Error message and stack trace
Steps to reproduce the issue
Network (mainnet/testnet) and transaction hash if applicable
Browser and OS information

Références

Ressources complémentaires pour le debugging et le support :

Documentation Complète

La documentation YaniPay est mise à jour en continu. Si vous trouvez une erreur non documentée, ouvrez une issue sur GitHub pour nous aider à l'améliorer.

Discord Community

Aide en temps réel

GitHub Issues

Rapporter un bug

Chrome DevTools

Guide debugging navigateur

Ethers.js Troubleshooting

Erreurs Web3 courantes

Related Resources

Community Support

Last updated: 2026-04-01

Troubleshooting

Solutions for common issues when building with YaniPay SDK.

Guide de Dépannage

Support Prioritaire

Les développeurs avec un plan Enterprise bénéficient d'un support prioritaire avec un temps de réponse garanti de 2h. Contactez support@yanipay.com pour toute question critique.

Cas d'Utilisation

MarcJunior Developer

Rencontre l'erreur "API key not found" lors de son premier déploiement en production.

✓ Problème résolu en 5 minutes grâce à la checklist de configuration

SophieFull Stack Developer

Debug une transaction qui échoue silencieusement en production sans message d'erreur clair.

✓ Identifie le problème de slippage grâce aux logs de simulation

LucasSupport Technique

Aide un utilisateur qui ne peut pas connecter son wallet MetaMask à l'application.

✓ Résolution rapide avec la checklist de connexion wallet

EmmaQA Engineer

Reproduit et documente un bug de rate limiting qui apparaît sous forte charge.

✓ Bug reproduit et fixé grâce aux outils de debug

Flux de Gestion d'Erreur

Voici comment les erreurs sont propagées et gérées dans l'architecture YaniPay :

Toujours Catch les Erreurs

Encapsulez toujours vos appels SDK dans un try/catch et gérez les erreurs de type YaniPayError pour afficher des messages utilisateur appropriés.

Common Errors

"API key not found" or "Invalid API key"

Cause: The API key is not configured or is incorrect.

Solution:

Check that NEXT_PUBLIC_YANIPAY_API_KEY is set in .env.local
Restart your development server after adding the variable
Verify the key is correct in your YaniPay dashboard

.env.localbash

# Make sure this is set correctly
NEXT_PUBLIC_YANIPAY_API_KEY=your_actual_api_key_here

"Module not found: Cannot find module '@/lib/api/client'"

Cause: L'alias de chemin @/ n'est pas résolu, ou le fichier n'existe pas.

Solution:

# Réinstaller les dépendances
rm -rf node_modules pnpm-lock.yaml
pnpm install

# Vérifier les dépendances installées
pnpm list

# Vérifier les types TypeScript
pnpm type-check

"SessionProvider not found in context" / "useSession must be wrapped in SessionProvider"

Cause: Un composant client utilise useSession() en dehors du SessionProvider.

Solution: Vérifier que SessionProvider et CartProvider enveloppent toute l'application dans app/layout.tsx :

app/layout.tsxtsx

import { SessionProvider } from 'next-auth/react';
import { CartProvider } from '@/components/CartProvider';

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        <SessionProvider>
          <CartProvider>
            {children}  {/* Tous les composants doivent être à l'intérieur */}
          </CartProvider>
        </SessionProvider>
      </body>
    </html>
  );
}

Wallet Connection Issues

"Failed to connect wallet"

Check browser extension

Ensure MetaMask or your wallet extension is installed and unlocked.

Check network

Make sure your wallet is connected to the correct network (mainnet or testnet).

Clear cache

Try disconnecting and reconnecting the wallet, or clearing browser cache.

"User rejected the request"

This means the user closed the wallet popup without confirming. Handle this gracefully:

try {
  await connect();
} catch (err) {
  if (err.code === 4001) {
    // User rejected - don't show error, just reset UI
    setConnecting(false);
  } else {
    // Actual error
    setError(err.message);
  }
}

Transaction Errors

"Insufficient balance"

Cause: Not enough tokens or gas.

Solution:

Check token balance before submitting transaction
Ensure wallet has enough native tokens for gas fees
Account for potential slippage when checking balance

// Check balance before swap
const balance = await yanipay.getBalance(tokenIn);
const requiredAmount = parseFloat(amountIn) * 1.005; // Include 0.5% buffer

if (parseFloat(balance) < requiredAmount) {
  throw new Error(`Insufficient ${tokenIn} balance. Need ${requiredAmount}, have ${balance}`);
}

"Transaction reverted"

Common causes:

Slippage too low for volatile markets
Transaction deadline expired
Insufficient liquidity in pool

// Increase slippage for volatile pairs
const swapParams = {
  ...params,
  slippage: '1.0', // Try 1% instead of 0.5%
  deadline: Date.now() + 30 * 60 * 1000, // 30 minute deadline
};

API Errors

Rate Limiting (429 Too Many Requests)

Solution: Implement request caching and debouncing.

import { useState, useEffect } from 'react';
import { useDebounce } from 'use-debounce';

function useCachedPrice(symbol: string) {
  const [price, setPrice] = useState(null);
  const [debouncedSymbol] = useDebounce(symbol, 500);

  useEffect(() => {
    // Check cache first
    const cached = localStorage.getItem(`price_${debouncedSymbol}`);
    if (cached) {
      const { value, timestamp } = JSON.parse(cached);
      if (Date.now() - timestamp < 30000) { // 30 second cache
        setPrice(value);
        return;
      }
    }

    // Fetch fresh data
    fetchPrice(debouncedSymbol).then((p) => {
      setPrice(p);
      localStorage.setItem(`price_${debouncedSymbol}`, JSON.stringify({
        value: p,
        timestamp: Date.now(),
      }));
    });
  }, [debouncedSymbol]);

  return price;
}

Network Errors

Solution: Implement retry logic with exponential backoff.

async function fetchWithRetry(url: string, maxRetries = 3) {
  let lastError;

  for (let i = 0; i < maxRetries; i++) {
    try {
      const response = await fetch(url);
      if (response.ok) return response.json();
      if (response.status < 500) throw new Error(await response.text());
    } catch (err) {
      lastError = err;
      // Exponential backoff: 1s, 2s, 4s
      await new Promise(r => setTimeout(r, 1000 * Math.pow(2, i)));
    }
  }

  throw lastError;
}

Debugging Tips

Mode Debug en Production

Ne laissez JAMAIS le mode debug activé en production ! Les logs peuvent exposer des informations sensibles comme les balances utilisateur ou les paramètres de transaction.

Enable Debug Mode

const yanipay = new YaniPay({
  apiKey: process.env.NEXT_PUBLIC_YANIPAY_API_KEY!,
  logging: {
    level: 'debug', // Shows all internal operations
    prefix: '[YaniPay]',
  },
});

Inspect Network Requests

Use browser DevTools (Network tab) to inspect API requests and responses. Look for:

Request URL and parameters
Response status codes
Response body for error messages

Check Transaction on Explorer

If a transaction fails, find it on the block explorer for more details:

try {
  const result = await yanipay.swap(params);
  console.log(`Success: https://explorer.yanichain.com/tx/${result.hash}`);
} catch (err) {
  if (err.transactionHash) {
    console.log(`Failed TX: https://explorer.yanichain.com/tx/${err.transactionHash}`);
  }
}

Getting Help

Discord Community

Join our Discord for real-time help from the community

GitHub Issues

Report bugs or request features on GitHub

When Reporting Issues

Include the following information:

Versions des dépendances (pnpm list)
Error message and stack trace
Steps to reproduce the issue
Network (mainnet/testnet) and transaction hash if applicable
Browser and OS information

Références

Ressources complémentaires pour le debugging et le support :

Documentation Complète

La documentation YaniPay est mise à jour en continu. Si vous trouvez une erreur non documentée, ouvrez une issue sur GitHub pour nous aider à l'améliorer.

Discord Community

Aide en temps réel

GitHub Issues

Rapporter un bug

Chrome DevTools

Guide debugging navigateur

Ethers.js Troubleshooting

Erreurs Web3 courantes

Related Resources

Community Support

Last updated: 2026-04-01