Format de réponse d'erreur
Toutes les erreurs API suivent un format cohérent :
{
"success": false,
"error": "Human-readable error message",
"details": [
{
"field": "amount",
"message": "Must be a positive number"
}
]
}Codes de statut HTTP
200OKRequête réussie
201CreatedRessource créée avec succès
400Bad RequestDonnées de requête invalides ou erreur de validation
401UnauthorizedAuthentification manquante ou invalide
403ForbiddenNon autorisé à accéder à cette ressource
404Not FoundRessource non trouvée
429Too Many RequestsLimite de débit dépassée
500Internal ErrorErreur serveur. Veuillez contacter le support
| Code | Statut | Description |
|---|---|---|
200 | OK | Requête réussie |
201 | Created | Ressource créée avec succès |
400 | Bad Request | Données de requête invalides ou erreur de validation |
401 | Unauthorized | Authentification manquante ou invalide |
403 | Forbidden | Non autorisé à accéder à cette ressource |
404 | Not Found | Ressource non trouvée |
429 | Too Many Requests | Limite de débit dépassée |
500 | Internal Error | Erreur serveur. Veuillez contacter le support |
Erreurs courantes
Erreurs de validation (400)
Données d'entrée invalidesLe corps de la requête ne correspond pas au schéma attendu. Vérifiez le tableau pour les erreurs de champs spécifiques.details
{
"success": false,
"error": "Invalid input data",
"details": [
{"path": ["amount"], "message": "Expected number, received string"},
{"path": ["token"], "message": "Invalid enum value. Expected 'USDC' | 'EURC'"}
]
}Montant invalideLe montant doit être compris entre 0,01 et 1 000 000.
Adresse du commerçant invalideLe ne correspond pas à l'adresse wallet du commerçant.toAddress
Erreurs d'authentification (401/403)
Aucun token fourniLe 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 invalideAPI 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
{
"success": false,
"error": "Human-readable message",
"code": "RATE_LIMIT_EXCEEDED",
"retryAfter": 60
}Codes d'erreur généraux
RATE_LIMIT_EXCEEDED429Limite de débit dépassée pour ce point d'accès
INVALID_UUID_FORMAT400Le paramètre ID n'est pas un UUID valide
MISSING_PARAMETER400Un paramètre requis est manquant
2FA_REQUIRED403L'opération nécessite l'activation de la 2FA
2FA_CODE_REQUIRED400Le code 2FA n'a pas été fourni
2FA_INVALID401Le code 2FA est incorrect ou expiré
SELF_TRANSFER_NOT_ALLOWED400Impossible de retirer vers votre propre wallet Fivo
INVALID_MERCHANT_ID400Le format du Merchant ID est invalide
WEBHOOK_LIMIT_REACHED400Nombre maximum de webhooks par commerçant atteint
REFUND_WINDOW_EXPIRED400La fenêtre de remboursement (180 jours) a expiré
REFUND_EXCEEDS_REMAINING400Le montant dépasse le solde remboursable
PAYMENT_NOT_COMPLETED400Le paiement n'est pas au statut complété
NO_SOURCE_ADDRESS400Le paiement n'a pas d'adresse source
REFUND_NOT_CANCELABLE400Le remboursement n'est pas au statut en attente
| Code | HTTP | Description |
|---|---|---|
RATE_LIMIT_EXCEEDED | 429 | Limite de débit dépassée pour ce point d'accès |
INVALID_UUID_FORMAT | 400 | Le paramètre ID n'est pas un UUID valide |
MISSING_PARAMETER | 400 | Un paramètre requis est manquant |
2FA_REQUIRED | 403 | L'opération nécessite l'activation de la 2FA |
2FA_CODE_REQUIRED | 400 | Le code 2FA n'a pas été fourni |
2FA_INVALID | 401 | Le code 2FA est incorrect ou expiré |
SELF_TRANSFER_NOT_ALLOWED | 400 | Impossible de retirer vers votre propre wallet Fivo |
INVALID_MERCHANT_ID | 400 | Le format du Merchant ID est invalide |
WEBHOOK_LIMIT_REACHED | 400 | Nombre maximum de webhooks par commerçant atteint |
REFUND_WINDOW_EXPIRED | 400 | La fenêtre de remboursement (180 jours) a expiré |
REFUND_EXCEEDS_REMAINING | 400 | Le montant dépasse le solde remboursable |
PAYMENT_NOT_COMPLETED | 400 | Le paiement n'est pas au statut complété |
NO_SOURCE_ADDRESS | 400 | Le paiement n'a pas d'adresse source |
REFUND_NOT_CANCELABLE | 400 | 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
E001Fonds insuffisants dans le wallet de l'expéditeur
E002Transaction annulée sur la blockchain
E003Délai d'attente réseau pendant la transaction
E004Adresse wallet invalide
E005Échec de l'estimation du gas
E006L'utilisateur a annulé la transaction
E007Échec de l'attestation CCTP
E999Erreur blockchain inconnue
| Code | Description |
|---|---|
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 :
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ête | Description |
|---|---|
Retry-After | Secondes à attendre avant de réessayer |
X-RateLimit-Limit | Nombre maximum de requêtes autorisées dans la fenêtre |
X-RateLimit-Remaining | Requêtes restantes dans la fenêtre actuelle |
X-RateLimit-Reset | Horodatage 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
| Point d'accès | Limite | Fenêtre | Par |
|---|---|---|---|
| Points d'accès API Key | 200 req | 1 minute | API Key |
| API générale | 100 req | 1 minute | IP |
| Création de paiement (widget) | 20 req | 1 minute | IP |
| Connexion | 5 req | 5 minutes | IP + e-mail |
| Inscription | 3 req | 15 minutes | IP |
| Réinitialisation du mot de passe | 3 req | 15 minutes | IP + e-mail |
| Vérification 2FA | 5 req | 5 minutes | IP |
| Retraits | 10 req | 10 minutes | IP |
| Formulaire de contact | 3 req | 15 minutes | IP |
Bonne pratique
Retry-AfterErreurs 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 paiementLe 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é
Exemple de gestion des erreurs
Voici comment gérer correctement les erreurs API dans votre code :
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