Catalogue d'erreurs
Tous les codes d'erreur retournés par l'API v1, avec la marche à suivre pour chacun.
Enveloppe d'erreur
Toutes les erreurs respectent ce format JSON :
{
"error": {
"type": "authorization_error",
"code": "insufficient_scope",
"message": "Cette clé API ne contient pas le scope requis pour cet endpoint.",
"hint": "Ajoute le scope 'leads:capture' à ta clé via le dashboard.",
"doc_url": "https://capturia.io/fr/developers/api/v1/authentication#scopes",
"dashboard_url": "https://app.capturia.io/platform/dashboard/admin/integrations/api-keys/ak_xxx",
"request_id": "req_01J9X8Z3F4K2M5N7P9Q1R3S5T7",
"details": {"required_scope": "leads:capture"}
}
}Tous les codes
| HTTP | Code | Type | Doc |
|---|---|---|---|
400 | invalid_encoding | validation_error | encoding |
400 | invalid_request | validation_error | invalid_request |
400 | validation_error | validation_error | validation_error |
401 | expired_api_key | authentication_error | expired_api_key |
401 | invalid_api_key | authentication_error | invalid_api_key |
401 | missing_api_key | authentication_error | missing_api_key |
401 | revoked_api_key | authentication_error | revoked_api_key |
403 | feature_not_available | authorization_error | plan |
403 | insufficient_scope | authorization_error | scopes |
403 | terms_acceptance_required | authorization_error | terms |
404 | resource_not_found | not_found_error | resource_not_found |
409 | confirmation_token_invalid | conflict_error | confirmation_token_invalid |
409 | duplicate_resource | conflict_error | duplicate_resource |
409 | idempotency_conflict | idempotency_error | idempotency |
409 | lead_disqualified | conflict_error | lead_disqualified |
409 | tag_managed_by_capturia | conflict_error | tag_managed_by_capturia |
413 | payload_too_large | validation_error | body-size |
415 | invalid_content_type | validation_error | content-type |
422 | business_rule_violation | business_rule_error | business_rule_violation |
422 | system_not_found | business_rule_error | system_not_found |
429 | rate_limit_exceeded | rate_limit_error | Voir |
429 | too_many_attempts | rate_limit_error | brute-force |
500 | internal_error | server_error | internal_error |
501 | not_implemented | server_error | not_implemented |
503 | service_unavailable | server_error | service_unavailable |
Détail des codes hébergés ici
Requête invalide invalid_request
Headers manquants, body trop gros, JSON invalide, ou paramètre query mal formé.
Hint — Vérifie Content-Type, taille body < 1MB, syntaxe JSON, et les params query.
Erreur de validation validation_error
Payload mal formé ou champ manquant. Le champ details.validation_errors[] liste les paths JSON Pointer fautifs.
Hint — Vérifie chaque path dans details.validation_errors[] et corrige le payload.
Ressource introuvable resource_not_found
L'ID fourni n'existe pas, ou n'est pas accessible avec cette clé.
Hint — Vérifie l'ID et que la ressource appartient bien à ton client.
Jeton de confirmation invalide confirmation_token_invalid
Le jeton retourné par preview_campaign ou preview_quote_send est invalide, expiré (10 minutes), déjà utilisé, lié à une autre clé API, ou la campagne ou la soumission a changé depuis l'aperçu.
Hint — Refais l'aperçu (preview_campaign ou preview_quote_send) pour obtenir un nouveau jeton, présente le résumé à l'humain, et confirme seulement après son accord explicite.
Ressource dupliquée duplicate_resource
Conflit d'unicité métier (ex. email déjà utilisé pour un contact).
Hint — Utilise PATCH/PUT pour mettre à jour la ressource existante au lieu de POST.
Lead disqualifié lead_disqualified
Le lead visé est disqualifié : son étape ne peut pas changer tant que la disqualification n'est pas levée. Déplacer vers une étape perdue, ou vers l'étape de disqualification, reste accepté.
Hint — Rouvre le lead depuis sa fiche dans le tableau de bord, puis rejoue la requête.
Tag géré par Capturia tag_managed_by_capturia
Le tag visé est un tag de campagne (system_key qui commence par campaign:). Capturia le pose sur chaque lead de la campagne et le retire quand le lead change de campagne : il ne s'attache ni ne se détache par l'API. Le filtrer pour compter les leads d'une campagne reste la bonne façon de s'en servir.
Hint — Pour changer la campagne d'un lead, choisis-la dans sa fiche du tableau de bord : le tag suit.
Règle métier violée business_rule_violation
L'opération est bloquée par une règle métier (ex. pipeline fermé, contact archivé).
Hint — Le champ details précise la règle. Voir la référence de l'endpoint pour les contraintes spécifiques.
Système introuvable system_not_found
Le system_id fourni à un endpoint de capture ne correspond à aucun Système actif de ce compte (UUID inconnu ou appartenant à un autre compte — la réponse est identique dans les deux cas). Aucun contact n'est créé.
Hint — Utilise l'UUID d'un de tes Systèmes, ou omets system_id pour cibler ton Système principal.
Erreur serveur internal_error
Bug Capturia. Le request_id permet à notre support de retrouver l'incident dans Sentry.
Hint — Réessaye après quelques secondes. Si ça persiste, contacte [email protected] avec le request_id.
Non implémenté not_implemented
Endpoint réservé pour usage futur (ex. clé cap_test_* sandbox).
Hint — Voir la référence pour les alternatives disponibles aujourd'hui.
Service indisponible service_unavailable
Maintenance ou dégradation temporaire d'un service amont.
Hint — Respecte le header Retry-After (secondes) avant de réessayer.