Catalog d'erreurs
Tous les codes d'erreur retournés par l'API v1, avec un hint d'action concret.
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 |
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
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.
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.
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.
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.
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.
Jeton de confirmation invalide confirmation_token_invalid
Le jeton retourné par preview_campaign est invalide, expiré (10 minutes), déjà utilisé, lié à une autre clé API, ou les paramètres de la campagne ont changé depuis la prévisualisation.
Hint — Refais un `preview_campaign` pour obtenir un nouveau jeton, présente le résumé à l'humain, et lance seulement après sa confirmation explicite.