Docs/Gestion des erreurs

Gestion des erreurs

Comprendre et gérer les erreurs de l'API Fivo.

Format de réponse d'erreur

Toutes les erreurs API suivent un format cohérent :

Error Response Structure
{
  "success": false,
  "error": "Human-readable error message",
  "details": [
    {
      "field": "amount",
      "message": "Must be a positive number"
    }
  ]
}

Codes de statut HTTP

200OK

Requête réussie

201Created

Ressource créée avec succès

400Bad Request

Données de requête invalides ou erreur de validation

401Unauthorized

Authentification manquante ou invalide

403Forbidden

Non autorisé à accéder à cette ressource

404Not Found

Ressource non trouvée

429Too Many Requests

Limite de débit dépassée

500Internal Error

Erreur serveur. Veuillez contacter le support

Erreurs courantes

Erreurs de validation (400)

Données d'entrée invalides

Le corps de la requête ne correspond pas au schéma attendu. Vérifiez le tableau pour les erreurs de champs spécifiques.details

json
{
  "success": false,
  "error": "Invalid input data",
  "details": [
    {"path": ["amount"], "message": "Expected number, received string"},
    {"path": ["token"], "message": "Invalid enum value. Expected 'USDC' | 'EURC'"}
  ]
}
Montant invalide

Le montant doit être compris entre 0,01 et 1 000 000.

Adresse du commerçant invalide

Le ne correspond pas à l'adresse wallet du commerçant.toAddress

Erreurs d'authentification (401/403)

Aucun token fourni

Le point d'accès protégé nécessite une authentification. Incluez l'en-tête ou .AuthorizationX-API-Key

Token invalide ou expiré

Le token JWT a expiré (durée de vie de 15 min) ou est mal formé. Réauthentifiez-vous pour obtenir un nouveau token.

API key invalide

API key non trouvée ou révoquée. Vérifiez que vous utilisez la bonne clé.

Erreurs de ressource (404)

Commerçant non trouvé

Aucun commerçant n'existe avec l'identifiant donné. Vérifiez votre .merchantId

Paiement non trouvé

Aucun paiement n'existe avec l'identifiant donné. Vérifiez que l'identifiant de paiement est correct.

Le paiement existe déjà

Un paiement avec ce existe déjà. L'API renvoie avec les données du paiement existant. Cela empêche les attaques de double dépense.txHash200

Codes d'erreur API

Lorsqu'une erreur survient, la réponse inclut un champ lisible par machine que vous pouvez utiliser pour la gestion programmatique des erreurs :code

Error Response with Code
{
  "success": false,
  "error": "Human-readable message",
  "code": "RATE_LIMIT_EXCEEDED",
  "retryAfter": 60
}

Codes d'erreur généraux

RATE_LIMIT_EXCEEDED429

Limite de débit dépassée pour ce point d'accès

INVALID_UUID_FORMAT400

Le paramètre ID n'est pas un UUID valide

MISSING_PARAMETER400

Un paramètre requis est manquant

2FA_REQUIRED403

L'opération nécessite l'activation de la 2FA

2FA_CODE_REQUIRED400

Le code 2FA n'a pas été fourni

2FA_INVALID401

Le code 2FA est incorrect ou expiré

SELF_TRANSFER_NOT_ALLOWED400

Impossible de retirer vers votre propre wallet Fivo

INVALID_MERCHANT_ID400

Le format du Merchant ID est invalide

WEBHOOK_LIMIT_REACHED400

Nombre maximum de webhooks par commerçant atteint

REFUND_WINDOW_EXPIRED400

La fenêtre de remboursement (180 jours) a expiré

REFUND_EXCEEDS_REMAINING400

Le montant dépasse le solde remboursable

PAYMENT_NOT_COMPLETED400

Le paiement n'est pas au statut complété

NO_SOURCE_ADDRESS400

Le paiement n'a pas d'adresse source

REFUND_NOT_CANCELABLE400

Le remboursement n'est pas au statut en attente

Codes d'erreur blockchain

Ces codes apparaissent dans le champ des paiements échoués :failure_reason

E001

Fonds insuffisants dans le wallet de l'expéditeur

E002

Transaction annulée sur la blockchain

E003

Délai d'attente réseau pendant la transaction

E004

Adresse wallet invalide

E005

Échec de l'estimation du gas

E006

L'utilisateur a annulé la transaction

E007

Échec de l'attestation CCTP

E999

Erreur blockchain inconnue

Limitation de débit

Lorsque vous dépassez les limites de débit, vous recevrez une réponse 429 avec des en-têtes supplémentaires :

Rate Limit Response
HTTP/1.1 429 Too Many Requests
Retry-After: 60
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1705312800

{
  "success": false,
  "error": "Rate limit exceeded",
  "message": "Too many requests. Please retry after 1 minute.",
  "code": "RATE_LIMIT_EXCEEDED",
  "retryAfter": 60,
  "context": "general"
}

En-têtes de limite de débit

En-têteDescription
Retry-AfterSecondes à attendre avant de réessayer
X-RateLimit-LimitNombre maximum de requêtes autorisées dans la fenêtre
X-RateLimit-RemainingRequêtes restantes dans la fenêtre actuelle
X-RateLimit-ResetHorodatage Unix de la réinitialisation de la limite

Limites de débit par point d'accès

Points d'accès API Key

200 req / 1 minute

Per: API Key

API générale

100 req / 1 minute

Per: IP

Création de paiement (widget)

20 req / 1 minute

Per: IP

Connexion

5 req / 5 minutes

Per: IP + e-mail

Inscription

3 req / 15 minutes

Per: IP

Réinitialisation du mot de passe

3 req / 15 minutes

Per: IP + e-mail

Vérification 2FA

5 req / 5 minutes

Per: IP

Retraits

10 req / 10 minutes

Per: IP

Formulaire de contact

3 req / 15 minutes

Per: IP

i

Bonne pratique

Implémentez un backoff exponentiel lorsque vous recevez des erreurs 429. Commencez avec la valeur et augmentez le temps d'attente pour les tentatives suivantes.Retry-After

Erreurs inter-chaînes

Les paiements inter-chaînes sont gérés côté client par Bridge Kit dans le widget. Si le transfert échoue (ex. délai d'attestation, échec du mint), le widget affiche l'erreur directement au client. Ces erreurs n'atteignent pas l'API backend.

Si un paiement inter-chaînes échoue après la transaction de burn, le client peut contacter le support avec son hash de transaction. Les paiements échoués stockent l'erreur dans le champ , accessible via l'API de statut de paiement.failure_reason

Détection de fraude

Fivo inclut une détection de fraude intégrée. Ces erreurs indiquent des attaques potentielles :

Échec de la vérification du montant du paiement

Le montant déclaré ne correspond pas au montant réel de la transaction blockchain. Cela pourrait indiquer une tentative de manipulation des enregistrements de paiement.

!

Sécurité

Les tentatives de fraude sont enregistrées avec tous les détails (IP, adresse wallet, transaction). Les tentatives répétées peuvent entraîner un blocage de l'IP.

Exemple de gestion des erreurs

Voici comment gérer correctement les erreurs API dans votre code :

JavaScript Error Handling
async function createCheckoutSession(data) {
  try {
    const response = await fetch('https://api.fivo.finance/checkout/sessions', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'X-API-Key': process.env.FIVO_API_KEY
      },
      body: JSON.stringify(data)
    });

    const result = await response.json();

    if (!response.ok) {
      // Handle specific error codes
      switch (response.status) {
        case 400:
          console.error('Validation error:', result.details);
          throw new Error('Invalid session data');

        case 401:
          console.error('Authentication failed');
          throw new Error('Please check your API key');

        case 429:
          const retryAfter = response.headers.get('Retry-After');
          console.log(`Rate limited. Retry after ${retryAfter}s`);
          throw new Error('Too many requests');

        default:
          throw new Error(result.error || 'Unknown error');
      }
    }

    return result.data;
  } catch (error) {
    console.error('Checkout session failed:', error.message);
    throw error;
  }
}

Vous avez encore des problèmes ?

Si vous rencontrez une erreur non listée ici, veuillez contacter le support avec :

  • La réponse d'erreur complète
  • Les détails de la requête (point d'accès, méthode, corps)
  • L'identifiant de paiement ou le hash de transaction (le cas échéant)
  • L'horodatage de l'erreur
Contacter le support