Codes d'erreur
Format JSON standard, codes métier et bonnes pratiques de gestion côté client.
Toutes les erreurs suivent le schéma ErrorResponse : error, message, details?, request_id?.
Succès
acceptedAcceptedÉvénements acceptés pour traitement asynchrone.
{ "accepted": 2, "rejected": 0, "duplicates": 0 }multi_statusMulti-StatusBatch partiellement accepté — certains événements ont échoué.
{
"accepted": 1,
"rejected": 1,
"duplicates": 0,
"results": [{ "event_id": "evt_dup", "status": "duplicate" }]
}Erreurs client (4xx)
validation_errorValidation ErrorPayload invalide ou paramètres manquants.
{
"error": "validation_error",
"message": "Invalid request payload",
"details": [{ "field": "events[0].event_type", "message": "Invalid event type" }],
"request_id": "req_abc123"
}Résolution : Vérifiez les types, champs requis et enums (event_type, dates ISO8601).
unauthorizedUnauthorizedClé API ou JWT manquant, expiré ou invalide.
{
"error": "unauthorized",
"message": "Invalid or missing API key"
}Résolution : Envoyez X-API-Key pour l'intégration ou Authorization: Bearer pour le dashboard.
forbiddenForbiddenAuthentifié mais sans permission sur la ressource.
{
"error": "forbidden",
"message": "Insufficient permissions"
}not_foundNot FoundRessource introuvable dans votre tenant.
{
"error": "not_found",
"message": "Customer not found"
}conflictConflictConflit métier (ex. ressource déjà existante).
{
"error": "conflict",
"message": "Resource already exists"
}rate_limitedRate LimitedQuota de requêtes dépassé.
{
"error": "rate_limited",
"message": "Too many requests"
}Résolution : Respectez Retry-After et implémentez un backoff exponentiel.
Erreurs serveur (5xx)
service_unavailableService UnavailableRate limiter indisponible (fail-closed) ou maintenance.
{
"error": "rate_limit_unavailable",
"message": "Service temporarily unavailable"
}Résolution : Réessayez après quelques secondes. Ne désactivez pas la sécurité côté client.
internal_errorInternal ErrorErreur serveur inattendue.
{
"error": "internal_error",
"message": "An unexpected error occurred",
"request_id": "req_xyz789"
}Résolution : Contactez le support avec request_id. Ne réessayez pas en boucle.