API keys et accès

Les échecs d'authentification sont les plus faciles à diagnostiquer, car l'API renvoie un code différent pour chaque cause. Ces codes ne correspondent pas toujours aux attentes : la validation renvoie 422, une mauvaise classe de clé renvoie 406, et le seul 409 parmi les problèmes d'authentification est celui de wajub logout sur une clé que wajub login n'a pas créée.

Erreur 401 Invalid API credentials

La clé n'est pas reconnue comme un identifiant utilisable. Deux messages reviennent, et le message indique quelle cause chercher :

La clé est vérifiée à chaque requête : une clé révoquée à l'instant cesse donc immédiatement de fonctionner.

Envoyez-la dans Authorization sans préfixe Bearer. L'API considère la valeur de l'en-tête comme la clé elle-même. Ajouter Bearer fait échouer la recherche comme toute faute de frappe.

curl https://api.wajub.com/payments \
  -H "Authorization: sk_test.xxxxxxxxxxxxxxxx…"

Erreur 403 Security Alert: You are trying to use a Private Key from a browser dans le navigateur

Wajub a détecté une clé sk. utilisée depuis un navigateur. Il refuse l'appel et envoie un e-mail au propriétaire de la clé.

Deux actions sont nécessaires. Déplacez l'appel vers votre serveur et considérez la clé comme divulguée. Elle se trouvait dans une application téléchargée par quelqu'un. Créez une clé de remplacement, déployez-la, puis supprimez l'ancienne. Bonnes pratiques de sécurité présente la procédure qui évite une interruption.

Erreur 403 IP address not allowed for this API key liée à l'adresse IP

La clé possède une liste d'IP autorisées et l'appelant n'y figure pas. Cette liste s'applique à tous les types de clés, y compris les clés publiques. Elle accepte des adresses IPv4 ou IPv6 exactes et des plages CIDR des deux familles. Une liste vide ne pose aucune restriction.

La cause habituelle est un déploiement qui modifie votre adresse de sortie ou un job exécuté depuis une machine non ajoutée. Comparez l'IP réelle de l'appelant à la liste de la clé.

Erreur 403 This API key does not have permission to read payment liée au scope

Une clé restreinte ne possède pas le scope exigé par la route. Les scopes suivent le format {resource}.{read|write}. Le verbe détermine la partie nécessaire : GET, HEAD et OPTIONS exigent read, les autres verbes exigent write.

Cette erreur possède une seconde forme importante.

Cette réponse ne signale pas un scope manquant. Une clé restreinte fonctionne comme une liste d'autorisations, pas comme un filtre. Si une route ne correspond à aucune ressource avec des scopes, aucune clé restreinte ne peut l'atteindre, quelles que soient ses autorisations. Quatre chemins font exception, car ils ne contiennent aucune donnée sensible : /channels, /countries, /currencies et la racine de l'API.

Deux ressources sont accessibles en lecture seule : balance et account. Une clé restreinte ne peut jamais les modifier et ne peut donc pas créer de connexion Sync. Utilisez pour cela une clé privée sur votre serveur.

Erreur 406 Private Key Required pour une clé publique

La route exige une clé privée, mais vous avez envoyé une clé publique. Cette règle concerne /balance, /transfers, /refunds, /disputes, /beneficiaries, /webhooks, /events, /identity, /accounts, /tax, /shield, /listen/sessions, les tax_ids d'un client, POST /payments/{id}/activate et PATCH /payments/{id}. Une connexion Sync se crée donc uniquement depuis votre serveur. Le tableau complet se trouve dans Authentification.

/payments ne figure pas dans cette liste : une clé publique peut créer un paiement. Le fait qu'un appel provenant d'une clé publique soit accepté ne signifie pas qu'il doit être effectué dans un navigateur.

Erreur 403 API access is currently restricted for this account. Contact support.

Wajub a restreint le compte, et la restriction ferme toute l'API, quelle que soit la clé envoyée. Le corps porte error_code: merchant_restricted et le type de restriction dans restriction. Une restriction plus étroite ne refuse que certains appels, avec son propre error_code : voir Erreurs de restriction. Contactez le support.

Erreur 403 This feature is only available in live mode.

Les liens, les factures et quelques autres routes réservées au live refusent une clé sandbox. Appelez-les avec une clé live une fois le compte vérifié.

Erreur 403 … is not included in your plan

Sync (/accounts, tout appel avec X-Sync) et Tax (/tax) demandent le produit dans votre plan ou une option active. Le corps porte error_code: feature_not_in_plan.

Erreur 403 sur un appel avec X-Sync

You are not authorized to access this Sync account. et Sync account not found. signifient que la connexion n'est pas la vôtre ou n'existe pas. Sync account is not active. donne son statut. This Sync account does not have the '…' permission. signifie que le marchand n'a pas accordé cette capacité. Payments and withdrawals are suspended for this Sync account. ne refuse que les appels qui déplacent de l'argent pendant que les paiements du marchand sont suspendus ; les lectures fonctionnent.

Erreur 400 Unsupported API version

L'en-tête X-Wajub-Version nomme une version que l'API ne sert pas. Le message liste celles qu'elle sert. Ce contrôle passe avant la clé : il peut donc revenir sur un appel dont la clé est aussi fausse.

Erreur 429 Too many requests

Une limite de requêtes, elle aussi contrôlée avant la clé. type dit quel compteur a déclenché et retry_after combien de temps attendre : voir Limites de requêtes.

« Je reçois une erreur CORS »

Ce n'est presque certainement pas le cas. Toutes les réponses de l'API, y compris les erreurs, contiennent Access-Control-Allow-Origin: *. Les requêtes préliminaires OPTIONS répondent avec 204, les méthodes et les en-têtes autorisés. Wajub ne produit pas d'erreurs CORS.

Le navigateur signale probablement l'une des situations suivantes comme une requête échouée.

Vérifiez surtout la dernière ligne dans l'onglet réseau. La requête préliminaire autorise Content-Type, Authorization, X-Requested-With, X-Request-Id, Idempotency-Key, X-Idempotency-Key, X-Sync, Accept, Origin et X-Wajub-Version. Tout autre en-tête fait échouer cette requête. Le navigateur signale alors une erreur CORS pour un appel que l'API n'a jamais examiné.

Réponse 404 pour un identifiant qui existe

La sandbox et le mode live ne partagent aucune donnée, et le préfixe de votre clé détermine celui que vous atteignez. Un identifiant d'un environnement n'existe réellement pas dans l'autre. La réponse est donc 404, pas une erreur d'autorisation. Les identifiants de la sandbox contiennent test_ après leur préfixe, ce qui permet de les reconnaître immédiatement.

La même règle s'applique entre les équipes. Un identifiant ne peut pas être résolu hors de l'équipe qui le possède. La réponse 404 est volontaire, car 403 confirmerait l'existence de l'objet.

Réponse 422 avec errors.idempotency_key

Vous avez réutilisé une Idempotency-Key avec un payload différent. Vous avez soit modifié un montant sans changer la clé, soit réutilisé une clé qui devait être renouvelée. Le problème n'est pas temporaire et une nouvelle tentative produit la même réponse.

Le format de la clé est aussi validé avant tout autre contrôle : A-Z, a-z, 0-9 et . _ : -, de 1 à 128 caractères. Un numéro de commande comme #4172 ou un UUID entre accolades est refusé à cause de son format.