référence
erreurs et limites de débit
Un paiement bloqué n'est pas une erreur : c'est un 200 avec le statut denied. Les erreurs concernent les mauvaises clés, les entrées invalides, les objets introuvables et les agents gelés.
issues métier (200)
Basez votre logique sur status, jamais sur le texte de reason :
| status | renvoyé par | que faire |
|---|---|---|
paid | pay | Terminé. Conservez transactionId. |
initiated | send_transfer | Virement soumis. Conservez paymentId. |
pending_approval | pay, send_transfer | Prévenez l'utilisateur qu'un humain doit approuver ; consultez get_request_status plus tard. Ne relancez pas. |
denied | pay, send_transfer | Le mandat l'interdit. Ne relancez pas, ne fractionnez pas ; rapportez reason. |
declined_by_bank | pay, send_transfer | L'émetteur a refusé : InsufficientFunds, CardSpendingLimitExceeded ou CardNotActivated. Demandez à un admin. |
erreurs http
Les erreurs renvoient un corps JSON {"error": "…"}, parfois avec details.
| code | quand | exemple |
|---|---|---|
400 | Entrée invalide (schéma, IBAN, montant, e-mail), demande déjà décidée, ou solde sandbox au-delà de 1 000 000 EUR. | IBAN invalide, Demande déjà executed |
401 | Clé absente ou invalide, ou agent révoqué. | Clé agent invalide, Clé admin invalide |
403 | Agent gelé ou inactif, ou route réservée à l'opérateur appelée avec une clé sandbox. | Agent gelé par l'entreprise : aucune dépense possible |
404 | Agent, demande ou espace introuvable (ou pas le vôtre). | Demande introuvable |
409 | Compte pas prêt côté banque. | |
429 | Limite sandbox atteinte : inscriptions, espaces par e-mail, 25 agents par espace. | Too many signups, try again in an hour |
500 | Erreur inattendue de notre côté. | Erreur interne |
502 | Le partenaire bancaire a renvoyé une erreur ; details contient sa réponse. |
{
"error": "Données invalides",
"details": [
{
"code": "too_small",
"minimum": 0,
"path": [
"amount"
],
"message": "Too small: expected number to be >0"
}
]
}status.erreurs mcp
| cas | forme |
|---|---|
| Clé invalide ou absente | HTTP 401, JSON-RPC error.code -32001 |
| Arguments non conformes au schéma | Résultat avec isError: true, texte commençant par MCP error -32602: Input validation error |
| Échec de l'outil (gelé, introuvable…) | Résultat avec isError: true et {"error": "…"} en texte |
| Outil inconnu | Erreur JSON-RPC ; l'outil n'est pas dans votre profil (clé agent ou admin). |
{
"jsonrpc": "2.0",
"error": {
"code": -32001,
"message": "Clé Nostro invalide (Bearer nst_... pour un agent, nsa_... pour l'admin d'un espace)"
},
"id": null
}limites de débit
La v0.1 n'a pas de quota de requêtes par clé sur les appels MCP et REST ; la sandbox sert au développement et aux démos, dans un usage raisonnable. Limites dures actuelles : inscription 10 par heure et par IP et 500 par heure au total, 3 espaces sandbox par e-mail, 25 agents actifs par espace, solde sandbox de 1 000 000 EUR maximum. Prévoyez tout de même des quotas de requêtes :
- Sur
429, attendezRetry-Afters'il est présent, sinon reculez de façon exponentielle (1 s, 2 s, 4 s, 30 s max). - Ne sondez pas
get_request_statusen boucle serrée : un humain met des minutes. Toutes les 30 à 60 secondes suffit.
relances et idempotence
pay n'a pas de clé d'idempotence en v0.1. Si un appel expire, ne relancez pas à l'aveugle : appelez d'abord list_my_activity pour vérifier si le paiement a été enregistré. Relancer un résultat denied ou pending_approval ne sert jamais à rien.