Erreurs et nouvelles tentatives
Les erreurs d'API utilisent un format cohérent. Le code concerne la logique applicative ; le message explique le problème. Conservez les entrées utilisateur intactes et proposez une prochaine étape claire.
Sur cette page
Un format d'erreur#
Les réponses n'incluent pas de traces de pile, SQL, jetons ni de réponse complète d'un fournisseur externe. N'affichez pas de journaux internes bruts à un client.
{
"error": {
"code": "GATEWAY_NOT_CONNECTED",
"message": "Financial operations are temporarily unavailable. Try later or contact support."
}
}Groupes d'erreurs courants#
| HTTP | Exemples | Prochaine étape |
|---|---|---|
| 400 | INVALID_JSON, UNKNOWN_FIELD, INVALID_INPUT | Vérifiez les entrées et les champs autorisés |
| 401 | AUTH_REQUIRED, SESSION_EXPIRED | Reconnectez-vous |
| 403 | INVALID_ORIGIN, CSRF_REQUIRED | Vérifiez l'origine et la session actuelle |
| 404 | NOT_FOUND, TICKET_NOT_FOUND | Vérifiez l'adresse et l'appartenance |
| 409 | CHALLENGE_UNAVAILABLE | Démarrez une nouvelle connexion |
| 410 | CHALLENGE_EXPIRED | Créez un nouveau lien de connexion |
| 413 | REQUEST_TOO_LARGE | Réduisez le corps de la requête |
| 415 | JSON_REQUIRED | Envoyez application/json |
| 429 | RATE_LIMITED | Réduisez la fréquence et attendez |
| 503 | GATEWAY_NOT_CONNECTED, SERVICE_UNAVAILABLE | Vérifiez la disponibilité ou réessayez plus tard |
Limites de débit#
| Action | Limite |
|---|---|
| Démarrage de la connexion | 6 par minute par adresse hachée |
| Vérification d'un défi | 90 par minute par défi |
| Question de connaissance | 12 par minute par adresse hachée avec D1 |
| Création d'un lien serveur | 20 par minute par utilisateur |
| API marchand | 90 requêtes par minute par clé |
| Nouvelle application | Cinq par jour par utilisateur |
| Reprise d'application / décision du modérateur | 30 par minute par utilisateur pour chaque action |
| Examen de site web par IA | 30 par heure pour l'ensemble du service |
| Lire le paiement ou tenter un paiement | 90 par minute par adresse hachée |
| Créer une demande d'assistance | 6 par heure par utilisateur |
| Tester une notification | 3 par heure par utilisateur |
| Génération par IA | 60 par heure pour l'ensemble du service par défaut |
Ce qui peut être réessayé#
Une lecture peut être réessayée après un délai lors d'une panne réseau temporaire. Avant de réessayer une mutation, vérifiez si l'opération d'origine a abouti ; une réponse perdue ne prouve pas un échec.
Les opérations financières exigent l'idempotence et une vérification de l'état du serveur. Une redirection du client vers une page de résultat ne remplace pas une confirmation.
Ce qu'il faut inclure dans une demande#
- La page et l'action immédiatement avant l'erreur.
- L'heure, le fuseau horaire et le code d'erreur visible.
- Votre référence de facture ou de demande d'assistance, si disponible.
- Une brève description du résultat attendu.