Codes d'erreur

Toutes les erreurs suivent une enveloppe JSON coherente :

{
  "error": {
    "code": "ERROR_CODE",
    "message": "Message lisible",
    "request_id": "req_...",
    "details": {}
  }
}

Codes d’erreur

Code	HTTP	Description	Action
UNAUTHORIZED	401	Token manquant, invalide ou revoque	Verifiez que votre token est correct et actif
FORBIDDEN	403	Restriction de scope, site, plan ou workspace	Verifiez le scope et l’acces aux sites
INVALID_METHOD	405	Methode HTTP non prise en charge sur cet endpoint	Utilisez la methode documentee dans la reference API
INVALID_PARAMS	422	Parametres de requete invalides ou non supportes	Corrigez les parametres selon la spec OpenAPI
RETENTION_EXCEEDED	422	La date from depasse la retention du plan	Ajustez from — consultez details.min_allowed_from
REPORT_RESPONSE_TOO_LARGE	422	La réponse de rapport sérialisée dépasse le budget dur de 5 MiB	Utilisez le summary Content ou réduisez la période/limite
RATE_LIMITED	429	Le token a depasse le rate limit	Attendez X-RateLimit-Reset et reessayez
HARD_CAP_REACHED	402	Quota mensuel epuise	Attendez la prochaine periode ou changez de plan
REPORT_LOCKED_BY_PROFILE	409	La famille de routes demandee requiert Extended	Utilisez un site/profil compatible ou restez sur une route Strict-safe
REPORT_NOT_AVAILABLE_FOR_REQUESTED_PERIOD	409	Le site est Extended aujourd’hui, mais la periode demandee precede les donnees Extended compatibles	Reessayez sur une periode plus recente et inspectez error.details.availability
NOT_FOUND	404	Endpoint inconnu	Verifiez le chemin de l’URL
SITE_NOT_FOUND	404	Une route dashboard/query demande un site inconnu	Verifiez le site_id selectionne et l’acces au workspace
SITE_INACTIVE	409	Une route dashboard/query demande un site inactif	Reactivez le site ou basculez vers un site actif
ANALYTICS_DB_TIMEOUT	503	La requete de la base analytique a depasse le delai	Reessayez avec une periode plus courte ou plus tard
ANALYTICS_DB_UNAVAILABLE	503	La base analytique est temporairement indisponible	Reessayez plus tard
INTERNAL_ERROR	500	Erreur backend inattendue	Reessayez avec backoff exponentiel

Exemples de reponses

UNAUTHORIZED (401)

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid API token",
    "request_id": "abc123"
  }
}

RATE_LIMITED (429)

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Rate limit exceeded for this token",
    "request_id": "abc123",
    "details": { "retry_after_seconds": 60 }
  }
}

Headers de reponse : X-RateLimit-Limit: 300, X-RateLimit-Remaining: 0, X-RateLimit-Reset: 1740000060.

RETENTION_EXCEEDED (422)

{
  "error": {
    "code": "RETENTION_EXCEEDED",
    "message": "Query start is outside plan retention",
    "request_id": "abc123",
    "details": { "min_allowed_from": "2025-12-01" }
  }
}

HARD_CAP_REACHED (402)

{
  "error": {
    "code": "HARD_CAP_REACHED",
    "message": "Hard cap reached for current billing period",
    "request_id": "abc123"
  }
}

REPORT_RESPONSE_TOO_LARGE (422)

{
  "error": {
    "code": "REPORT_RESPONSE_TOO_LARGE",
    "message": "The report response exceeds the maximum response budget.",
    "request_id": "abc123",
    "details": {
      "include": "full",
      "range_days": 90,
      "measured_bytes": 5300000,
      "max_bytes": 5242880
    }
  }
}

Ce rejet n’est pas tronqué et consomme zéro unité.

REPORT_LOCKED_BY_PROFILE (409)

{
  "error": {
    "code": "REPORT_LOCKED_BY_PROFILE",
    "message": "This report requires Extended collection for the selected site.",
    "request_id": "abc123",
    "details": {
      "route": "goals",
      "classification": "extended_only",
      "currentProfile": "strict",
      "availability": {
        "route": "goals",
        "classification": "extended_only",
        "currentProfile": "strict",
        "collectionProfileEffectiveAt": "2026-03-18T09:00:00.000Z",
        "current": {
          "status": "locked_by_profile",
          "reason": "extended_data_required",
          "requestedStart": "2026-03-01T00:00:00.000Z",
          "requestedEnd": "2026-03-31T23:59:59.999Z",
          "compatibleStart": null,
          "compatibleEnd": null
        },
        "compare": null,
        "sections": []
      }
    }
  }
}

Comportement client recommande

• Toujours logger request_id en cas d’echec pour le support
• Reessayer avec backoff exponentiel pour 500 INTERNAL_ERROR
• Attendre X-RateLimit-Reset avant de reessayer 429 RATE_LIMITED
• Ne pas reessayer 401, 403, 402, 422 — corrigez la requete ou la config du token
• Pour 409 REPORT_LOCKED_BY_PROFILE ou REPORT_NOT_AVAILABLE_FOR_REQUESTED_PERIOD, inspectez error.details.availability puis ajustez la famille de routes ou la periode demandee
• Pour les routes mixtes qui restent en 200, inspectez d’abord availability.readModel pour identifier le socle strict-safe, puis availability.sections pour detecter les slices d’attribution ou d’actions avancees encore verrouillees en Strict
• Pour 402 HARD_CAP_REACHED, verifiez l’usage avec GET /v1/usage/current et attendez la prochaine periode

Erreurs de configuration de site dans le dashboard

Le dashboard et le control plane utilisent aussi des codes stables centres sur le concept de site pendant l’enregistrement et la verification :

Code	Signification	Action typique
INVALID_SITE_HOSTNAME	Le hostname saisi est invalide	Entrer un hostname valide, sans email ni chemin inutile
SITE_SCOPE_NOT_ALLOWED	Le scope large demande n’est pas autorise pour ce hostname	Suivre ce site hostname par hostname
HOSTNAME_PATTERN_OUT_OF_SCOPE	Un hostname avance sort du perimetre du site	Creer un autre site ou ajuster l’allowlist
SITE_SCOPE_ALREADY_CLAIMED	Un autre espace a deja verifie ce scope	Contacter le support si le périmètre de site doit etre transfere
SITE_DNS_VERIFICATION_FAILED	Le TXT n’a pas encore ete trouve	Verifier le nom, la valeur et la propagation DNS
SITE_DNS_VERIFICATION_UNAVAILABLE	La verification DNS ne s’applique pas a ce type de site	Continuer la collecte et ignorer cette etape pour l’instant