200 | Systèmes actifs du compte. |
401 | La clé API manque, est inconnue ou a expiré. code distingue les trois
causes : missing_api_key (aucun en-tête Authorization: Bearer),
invalid_api_key (clé inconnue, révoquée ou de format invalide) et
expired_api_key (date d'expiration dépassée). missing_api_key
{
"error": {
"type": "authentication_error",
"code": "missing_api_key",
"message": "Aucune clé API n'a été fournie.",
"hint": "Ajoute un header Authorization sous la forme : Bearer cap_live_<ta_clé>",
"doc_url": "https://capturia.io/fr/developers/api/v1/authentication#missing_api_key",
"request_id": "req_01J9X8Z3F4K2M5N7P9Q1R3S5T7"
}
}
invalid_api_key
{
"error": {
"type": "authentication_error",
"code": "invalid_api_key",
"message": "La clé API est invalide ou a été révoquée.",
"hint": "Vérifie la clé dans ton dashboard ou génère-en une nouvelle.",
"doc_url": "https://capturia.io/fr/developers/api/v1/authentication#invalid_api_key",
"request_id": "req_01J9X8Z3F4K2M5N7P9Q1R3S5T7"
}
}
expired_api_key
{
"error": {
"type": "authentication_error",
"code": "expired_api_key",
"message": "La clé API a expiré.",
"hint": "Roule la clé depuis le dashboard pour en générer une nouvelle valide.",
"doc_url": "https://capturia.io/fr/developers/api/v1/authentication#expired_api_key",
"request_id": "req_01J9X8Z3F4K2M5N7P9Q1R3S5T7"
}
}
|
403 | Refus d'autorisation. code distingue les refus que l'opération rend sous ce statut, et chaque exemple en montre un. insufficient_scope : la clé n'a ni contacts:read ni webhooks:manage ; le refus nomme contacts:read. feature_not_available : details.feature nomme ce qui manque, l'API publique au forfait du compte (public_api) ou les Systèmes, pas encore ouverts à l'API pour ce compte (systems). browser_not_allowed
{
"error": {
"type": "authorization_error",
"code": "browser_not_allowed",
"message": "Les clés API s'utilisent depuis un serveur, jamais depuis un navigateur.",
"hint": "La requête porte un en-tête `Origin` : appelle l'API depuis ton serveur, où la clé reste secrète.",
"doc_url": "https://capturia.io/fr/developers/api/v1/errors#browser_not_allowed",
"request_id": "req_01J9X8Z3F4K2M5N7P9Q1R3S5T7"
}
}
account_suspended
{
"error": {
"type": "authorization_error",
"code": "account_suspended",
"message": "L'accès à ce compte est suspendu par l'équipe Capturia.",
"hint": "Le refus vient du compte, pas de la clé. Tant que la suspension dure, aucune requête n'est acceptée : contacte l'équipe Capturia.",
"doc_url": "https://capturia.io/fr/developers/api/v1/authentication#account_suspended",
"request_id": "req_01J9X8Z3F4K2M5N7P9Q1R3S5T7"
}
}
feature_not_availablepublic_api
{
"error": {
"type": "authorization_error",
"code": "feature_not_available",
"message": "Cette fonctionnalité n'est pas incluse dans ton forfait.",
"hint": "Le refus vient du forfait du compte, pas de la clé. Contacte ton conseiller Capturia pour en parler.",
"doc_url": "https://capturia.io/fr/developers/api/v1/authentication#plan",
"request_id": "req_01J9X8Z3F4K2M5N7P9Q1R3S5T7",
"details": {
"feature": "public_api"
}
}
}
insufficient_scope
{
"error": {
"type": "authorization_error",
"code": "insufficient_scope",
"message": "Cette clé API ne contient pas le scope requis pour ce point d'accès.",
"hint": "Cette clé n'a pas le scope `contacts:read`. Crée une nouvelle clé avec le preset « Lecture seule » ou ajoute le scope via le dashboard.",
"doc_url": "https://capturia.io/fr/developers/api/v1/authentication#scopes",
"dashboard_url": "https://capturia.io/platform/dashboard/admin/integrations/api-keys/6f1e2d3c-4b5a-4c6d-8e7f-9a0b1c2d3e4f?tab=permissions",
"request_id": "req_01J9X8Z3F4K2M5N7P9Q1R3S5T7",
"details": {
"required_scope": "contacts:read",
"current_scopes": [
"leads:capture"
],
"suggested_preset": "read_only"
}
}
}
feature_not_availablesystems
{
"error": {
"type": "authorization_error",
"code": "feature_not_available",
"message": "Cette fonctionnalité n'est pas encore ouverte pour ce compte.",
"hint": "Capturia l'ouvre compte par compte avant son lancement ; le refus vient du compte, pas de la clé. `details.feature` la nomme. Contacte ton conseiller Capturia pour la faire ouvrir.",
"doc_url": "https://capturia.io/fr/developers/api/v1/authentication#plan",
"request_id": "req_01J9X8Z3F4K2M5N7P9Q1R3S5T7",
"details": {
"feature": "systems"
}
}
}
|
429 | Limite de débit atteinte. rate_limit_exceeded : le quota horaire de la
clé est épuisé. too_many_attempts : trop de clés invalides présentées
depuis cette adresse IP (protection contre la force brute). Dans les deux
cas, Retry-After donne le délai en secondes. rate_limit_exceeded
{
"error": {
"type": "rate_limit_error",
"code": "rate_limit_exceeded",
"message": "Limite de requêtes atteinte.",
"hint": "Réessaie après le nombre de secondes indiqué dans retry_after_seconds, et envisage d'implémenter un backoff exponentiel.",
"doc_url": "https://capturia.io/fr/developers/api/v1/rate-limits",
"request_id": "req_01J9X8Z3F4K2M5N7P9Q1R3S5T7",
"details": {
"limit": 100,
"count": 100,
"limit_type": "per_key",
"retry_after_seconds": 42
}
}
}
too_many_attempts
{
"error": {
"type": "rate_limit_error",
"code": "too_many_attempts",
"message": "Trop de tentatives d'authentification invalides depuis cette IP.",
"hint": "Attends la période indiquée par retry_after_seconds avant de réessayer.",
"doc_url": "https://capturia.io/fr/developers/api/v1/authentication#brute-force",
"request_id": "req_01J9X8Z3F4K2M5N7P9Q1R3S5T7",
"details": {
"limit_type": "brute_force",
"retry_after_seconds": 300
}
}
}
|
500 | Erreur serveur inattendue. Toujours fournir le request_id au support. internal_error
{
"error": {
"type": "server_error",
"code": "internal_error",
"message": "Erreur serveur. L'équipe Capturia a été notifiée.",
"hint": "Si le problème persiste, contacte le support en incluant le request_id de cette réponse.",
"doc_url": "https://capturia.io/fr/developers/api/v1/errors#internal_error",
"request_id": "req_01J9X8Z3F4K2M5N7P9Q1R3S5T7"
}
}
|
501 | Les clés de test (cap_test_) ne sont pas encore servies : seules les clés
cap_live_ sont acceptées. not_implemented
{
"error": {
"type": "server_error",
"code": "not_implemented",
"message": "Cette fonctionnalité n'est pas encore implémentée.",
"hint": "Consulte la documentation API pour les fonctionnalités disponibles et le changelog pour les prochaines versions.",
"doc_url": "https://capturia.io/fr/developers/api/v1/errors#not_implemented",
"request_id": "req_01J9X8Z3F4K2M5N7P9Q1R3S5T7"
}
}
|
503 | Un service dont la requête dépend n'a pas répondu (lecture de la clé, du
compte ou du forfait). La même requête passera quand il reviendra :
réessaie après le délai de Retry-After. service_unavailable
{
"error": {
"type": "server_error",
"code": "service_unavailable",
"message": "Service temporairement indisponible.",
"hint": "Réessaie après la période indiquée par Retry-After.",
"doc_url": "https://capturia.io/fr/developers/api/v1/errors#service_unavailable",
"request_id": "req_01J9X8Z3F4K2M5N7P9Q1R3S5T7"
}
}
|