Question 1

Erreur 402 « insufficient_balance » : que faire ?

Accepted Answer

Votre solde wallet est inférieur à 0,10 €. Aucun débit n'a eu lieu, le job a été automatiquement marqué failed. Rechargez sur l'onglet Facturation puis relancez la requête.

Question 2

Erreur 401 « invalid_api_key » alors que ma clé existe.

Accepted Answer

Vérifiez : (1) le préfixe est bien crw_live_, (2) la clé n'a pas été révoquée dans l'onglet Clés API, (3) le header est Authorization: Bearer (ou x-crawlers-key: ), sans espace parasite.

Question 3

Mon paiement Paddle a été débité mais le wallet n'est pas crédité.

Accepted Answer

Le crédit est asynchrone via webhook Paddle (idempotent). Attendez 30 s puis rafraîchissez. Si après 5 minutes le solde n'a pas bougé, contactez dev@crawlers.fr avec votre identifiant de transaction Paddle (visible dans l'email de reçu).

Question 4

Puis-je obtenir un remboursement d'un job en échec ?

Accepted Answer

Les jobs marqués failed pour cause de erreur serveur (500, timeout, feature en panne) sont recrédités automatiquement sous 24 h. Les jobs failed pour input invalide (400) ne sont pas remboursés — le crédit a déjà été consommé par la validation.

Question 5

Comment fonctionne le mode test vs production ?

Accepted Answer

En preview (édition Lovable), les paiements sont en mode sandbox Paddle : aucun argent réel n'est prélevé, utilisez les cartes de test (4242 4242 4242 4242). Une fois publié, le mode live est automatiquement activé.

Question 6

Quels moyens de paiement sont acceptés ?

Accepted Answer

Cartes Visa / Mastercard / Amex, PayPal, Apple Pay et Google Pay selon votre région. Le paiement par virement SEPA n'est pas disponible pour les top-ups wallet (montants trop faibles).

Question 7

Le wallet a-t-il une date d'expiration ?

Accepted Answer

Non. Le crédit reste disponible sans limite de durée tant que votre compte est actif.

Question 8

Puis-je obtenir une facture pour ma comptabilité ?

Accepted Answer

Chaque top-up génère automatiquement une facture Paddle (TVA incluse selon votre pays) envoyée par email. Historique disponible dans l'onglet Facturation → Transactions.

Question 9

Combien coûte exactement un appel API ?

Accepted Answer

0,10 € HT par job, quel que soit le module appelé (audit_expert, geo_score, cocoon, etc.). Pas d'abonnement, pas de frais cachés.

Question 10

Que se passe-t-il si mon webhook ne répond pas ?

Accepted Answer

Les webhooks ont un timeout de 10 s. En cas d'échec, le résultat reste consultable via GET /v1/jobs/{id}. Crawlers ne retente pas automatiquement les webhooks pour l'instant.

HTTP	Code	À faire
400	invalid_json / missing_field / unknown_feature	Corriger le payload. Pas de débit.
401	missing_api_key / invalid_api_key	Vérifier le header Authorization. Pas de débit.
402	insufficient_balance	Recharger le wallet. Pas de débit, job marqué failed.
404	job_not_found	L'id du job n'existe pas ou n'appartient pas à votre clé.
409	not_cancellable	Le job est déjà terminé (completed/failed/cancelled).
429	rate_limited	Respecter Retry-After. Pas de débit sur les requêtes refusées.
500	db_error / internal_error	Erreur serveur — retry avec backoff exponentiel. Crédit remboursé sous 24 h si le job a été débité.

Wallet & paiement

Guide pas-à-pas

Codes de retour POST /v1/jobs

Questions fréquentes

Toujours bloqué ?