Erreurs¶

Référence des codes d'erreur et des réponses d'erreur de l'API.

Format des erreurs¶

Toutes les erreurs suivent le même format :

{
  "error": "Description de l'erreur"
}

Codes HTTP¶

400 Bad Request¶

La requête est invalide ou l'opération n'est pas permise.

Erreur	Cause	Solution
`DEPOSIT requests require an amount greater than 0`	Création d'un pré-paiement sans montant	Ajouter un champ `amount` positif
`Cannot cancel a payment request in terminal status`	Tentative d'annulation d'une demande déjà finalisée	Vérifier le statut avant d'annuler

Exemple :

curl -X POST \
  -H "X-API-Key: votre-clé-api" \
  -H "Content-Type: application/json" \
  -d '{"request_type": "DEPOSIT", "amount": 0, "guest_email": "a@b.com", "guest_first_name": "A", "guest_last_name": "B", "reservation_ref": "R1"}' \
  https://votre-domaine.com/api/payment-requests/

HTTP/1.1 400 Bad Request

{
  "error": "DEPOSIT requests require an amount greater than 0"
}

401 Unauthorized¶

Authentification requise ou clé API invalide.

Cause	Solution
Header `X-API-Key` absent	Ajouter l'en-tête `X-API-Key`
Clé API invalide ou désactivée	Vérifier la clé dans l'administration

Exemple :

curl https://votre-domaine.com/api/payment-requests/

HTTP/1.1 401 Unauthorized

{
  "detail": "Unauthorized"
}

404 Not Found¶

La ressource demandée n'existe pas.

Cause	Solution
UUID de demande inexistant	Vérifier l'UUID
Demande appartenant à un autre tenant	L'isolation multi-tenant empêche l'accès

Exemple :

HTTP/1.1 404 Not Found

{
  "error": "Payment request 00000000-0000-0000-0000-000000000000 not found."
}

422 Unprocessable Entity¶

Les données envoyées ne respectent pas le schéma attendu.

Cause	Solution
Champ requis manquant	Inclure tous les champs requis
Type de donnée incorrect	Vérifier les types (string, number, etc.)

429 Too Many Requests¶

Limite de débit dépassée (rate limiting).

Endpoint	Limite
`POST /api/payment-requests/`	Via clé API
Formulaire de paiement	30 requêtes/minute par IP
IPN (webhook)	60 requêtes/minute par IP

Réponse :

HTTP/1.1 429 Too Many Requests

{
  "error": "Too many requests."
}

Bonne pratique

Implémentez un backoff exponentiel en cas de 429. Attendez quelques secondes avant de réessayer.

500 Internal Server Error¶

Erreur interne du serveur. Contactez le support si le problème persiste.

Erreurs courantes par endpoint¶

POST /api/payment-requests/¶

Scénario	Code	Message
DEPOSIT sans montant	400	`DEPOSIT requests require an amount greater than 0`
Champ requis manquant	422	Détails de validation
Clé API invalide	401	`Unauthorized`

GET /api/payment-requests/{uuid}/¶

Scénario	Code	Message
UUID inexistant	404	`Payment request {uuid} not found.`
Clé API invalide	401	`Unauthorized`

POST /api/payment-requests/{uuid}/cancel/¶

Scénario	Code	Message
UUID inexistant	404	`Payment request {uuid} not found.`
Statut terminal	400	Message de validation
Clé API invalide	401	`Unauthorized`

DELETE /api/payment-requests/{uuid}/¶

Scénario	Code	Message
UUID inexistant	404	`Payment request {uuid} not found.`
Clé API invalide	401	`Unauthorized`

Bonnes pratiques de gestion d'erreurs¶

Toujours vérifier le code HTTP avant de parser le corps de la réponse
Logger les erreurs avec le corps complet de la réponse pour le diagnostic
Implémenter un retry avec backoff exponentiel pour les erreurs 429 et 5xx
Ne pas retenter les erreurs 400, 401 et 404 — elles nécessitent une correction

import requests
import time

def api_call_with_retry(url, headers, max_retries=3):
    for attempt in range(max_retries):
        response = requests.get(url, headers=headers)

        if response.status_code == 429:
            wait = 2 ** attempt
            time.sleep(wait)
            continue

        if response.status_code >= 500:
            wait = 2 ** attempt
            time.sleep(wait)
            continue

        return response

    raise Exception("Max retries exceeded")