Erreurs et limites

Les erreurs de gestion contiennent error (lisible par un humain) et code (stable). Décidez selon code et le statut HTTP, pas selon le texte du message. Les erreurs de Scope peuvent inclure required et missing_scope ; les réponses réessayables peuvent inclure retryAfter, retryable et Retry-After. Les échecs de propriété renvoient 404 pour ne pas révéler les ressources d’un autre wallet.

{ "error": "Insufficient scope", "code": "insufficient_scope", "required": "write" }

• 400 : JSON invalide, requête invalide ou destination rejetée.
• 401 : authentification manquante/invalide ou signature rejetée.
• 402 : crédits insuffisants ou capacité en slots requise.
• 403 : Scope insuffisant ou autre restriction de permission explicite.
• 404 : ressource manquante ou étrangère.
• 409 : conflit, réservation d’idempotence active, clé réutilisée ou actif en pause.
• 410 : brouillon de rechargement expiré.
• 422 : échec de la vérification du paiement.
• 429 : limite de débit ou capacité de repli de sécurité épuisée.
• 503 : prix, signer ou dépendance transitoire indisponible.

Respectez Retry-After et utilisez un backoff exponentiel avec jitter et un budget fini de tentatives. Répétez une opération idempotente avec la même clé et le même corps. Ne réessayez pas aveuglément les échecs d’authentification ni les permissions refusées. N’achetez jamais un second abonnement simplement parce que la première réponse a expiré. Ne renouvelez un devis ou un brouillon que lorsque l’instruction existante n’est plus utilisable.

Le challenge et l’échange de token sont limités à 30 requêtes par minute et par IP. Les brouillons de rechargement, les achats d’abonnement et la création de watches sont limités à 10 par minute et par wallet. Les PATCH/DELETE de watch autorisent 60 par minute ; le PUT des paramètres et l’aperçu de message autorisent 30 par minute ; l’export d’alertes autorise 10 par heure. Les limites s’appliquent avant l’idempotence, rejeux compris. Un repli borné local au processus est utilisé lorsque Redis est indisponible ; les limites de sécurité se ferment lorsque la capacité de repli est épuisée.

La création de destinataires et les changements de cible partagent 10 par heure et par wallet. Le mail de confirmation a des budgets par wallet et par destination canonique. Un renvoi limité peut renvoyer HTTP 200 avec sent: false au lieu de 429 ; inspectez ce champ. La création d’un destinataire peut signaler confirmationSent: false. Une cible en attente reste non vérifiée et ne peut recevoir ni tests ni alertes.

Le ledger de compte et la liste des watches acceptent limit et un cursor opaque. Suivez nextCursor jusqu’à null ; n’interprétez ni ne modifiez un Cursor. L’historique des alertes utilise à la place page à base zéro et pageSize avec filtres et tri. L’export est borné à 5 000 lignes. Ne mélangez pas les deux modèles de pagination.

curl 'https://ftso.app/api/x402/watches?limit=20' \
  -H 'authorization: Bearer fbx_READ_TOKEN'
# Follow the returned nextCursor, URL-encoded, on the next request.

L’énumération complète des codes stables est publiée dans le document OpenAPI. Voir la référence des opérations pour les permissions.