Erreurs, reprises & limites
Idempotence : réessayer sans risque
Chaque POST exige un en-tête Idempotency-Key, unique par action (un UUID est idéal). Si le réseau coupe et que vous ne savez pas si Fidelia a reçu l’appel, renvoyez-le avec la même clé et le même corps :
- si le premier appel est passé, vous recevez à nouveau sa réponse (avec
Idempotent-Replayed: true), et rien n’est fait deux fois ; - sinon, il s’exécute maintenant.
La même clé avec un autre corps répond 409 idempotency_mismatch. Les clés sont conservées 24 heures.
Si Fidelia est injoignable, ne bloquez pas le client : terminez la vente et réessayez plus tard avec la même clé.
Erreurs
Les erreurs ont un statut HTTP et un code stable sur lequel brancher votre logique :
{ "error": "insufficient_balance", "message": "The card balance is too low.", "request_id": "6f1c…" }message est en anglais, pour vos journaux. field nomme le paramètre invalide en 400 ; detail précise parfois la règle non respectée.
| Statut | Codes |
|---|---|
| 400 | invalid_input (avec field), invalid_location |
| 401 | invalid_key |
| 402 | plan_required (le commerce n’a pas Pro), subscription_inactive |
| 403 | scope_denied |
| 404 | card_not_found, receipt_not_found, pairing_not_found, milestone_not_found, not_found |
| 409 | insufficient_balance, insufficient_points, insufficient_items, not_ready, already_claimed, reward_ready, wrong_card_type, pack_inactive, membership_expired, membership_inactive, program_inactive, already_reversed, reverse_conflict, reverse_window_expired, idempotency_mismatch |
| 410 | card_voided (le commerce a effacé ce client), pairing_expired, pairing_collected |
| 429 | rate_limited : attendez Retry-After secondes |
| 500 | internal_error : réessayez plus tard avec la même clé d’idempotence |
Limites de débit
Par clé : 10 requêtes par seconde et 20 000 par jour. Au-delà, vous recevez 429 avec Retry-After. Besoin de plus ? Demandez-nous.
Délais
Utilisez un délai d’attente de 10 secondes. La plupart des appels répondent en bien moins d’une seconde.
Versions
La version est dans l’URL (/v1). Dans la v1, nous ne faisons qu’ajouter : nouveaux champs, nouveaux points d’accès, nouveaux codes reason ou d’erreur. Ignorez les champs inconnus, et traitez un code d’erreur inconnu selon son statut HTTP. Un changement incompatible viendrait en /v2, annoncé à l’avance. Voir l’historique des versions.
Support
Envoyez-nous le X-Request-Id de l’appel : il nous permet de le retrouver dans nos journaux. support@fidelia.se