ZedCheckout

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

202acceptedAccepted

Événements acceptés pour traitement asynchrone.

{ "accepted": 2, "rejected": 0, "duplicates": 0 }
207multi_statusMulti-Status

Batch partiellement accepté — certains événements ont échoué.

{
  "accepted": 1,
  "rejected": 1,
  "duplicates": 0,
  "results": [{ "event_id": "evt_dup", "status": "duplicate" }]
}

Erreurs client (4xx)

400validation_errorValidation Error

Payload 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).

401unauthorizedUnauthorized

Clé 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.

403forbiddenForbidden

Authentifié mais sans permission sur la ressource.

{
  "error": "forbidden",
  "message": "Insufficient permissions"
}
404not_foundNot Found

Ressource introuvable dans votre tenant.

{
  "error": "not_found",
  "message": "Customer not found"
}
409conflictConflict

Conflit métier (ex. ressource déjà existante).

{
  "error": "conflict",
  "message": "Resource already exists"
}
429rate_limitedRate Limited

Quota 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)

503service_unavailableService Unavailable

Rate 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.

500internal_errorInternal Error

Erreur 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.