Gestion des erreurs
L'API retourne des codes HTTP standards accompagnés de messages d'erreur structurés.
Format des erreurs
Toutes les erreurs suivent ce format :
{
"error": {
"code": "ERROR_CODE",
"message": "Description lisible de l'erreur"
}
}
Codes HTTP
| Code | Signification | Quand |
|---|---|---|
200 | OK | Requête réussie |
401 | Unauthorized | Authentification manquante ou invalide |
402 | Payment Required | Crédits insuffisants |
403 | Forbidden | Scope insuffisant |
404 | Not Found | Ressource non trouvée |
429 | Too Many Requests | Rate limit dépassé |
500 | Internal Server Error | Erreur serveur |
Codes d'erreur communs
Authentification
{
"error": {
"code": "MISSING_API_KEY",
"message": "Header Authorization manquant"
}
}
{
"error": {
"code": "INVALID_API_KEY",
"message": "Clé API invalide ou révoquée"
}
}
Permissions
{
"error": {
"code": "INSUFFICIENT_SCOPE",
"message": "Scope 'appointments:create' requis"
}
}
Ressources
{
"error": {
"code": "APPOINTMENT_NOT_FOUND",
"message": "Rendez-vous avec id 12345 non trouvé"
}
}
Rate Limiting
{
"error": {
"code": "RATE_LIMIT_EXCEEDED",
"message": "Rate limit exceeded. Try again in 3600 seconds"
}
}
Headers : Retry-After: 3600
Crédits
{
"error": {
"code": "INSUFFICIENT_CREDITS",
"message": "Votre organisation a 0 crédits restants"
}
}
Gestion des erreurs dans le code
Avec cURL
response=$(curl -s -w "\n%{http_code}" ...)
http_code=$(echo "$response" | tail -n1)
body=$(echo "$response" | head -n-1)
if [ $http_code -ne 200 ]; then
echo "Erreur: $body"
fi
Avec les SDKs
Les SDKs gèrent automatiquement les erreurs avec des exceptions typées :
try {
const appointment = await client.appointments.create({...});
} catch (error) {
if (error.code === 'INSUFFICIENT_CREDITS') {
// Rediriger vers page de recharge
} else if (error.code === 'RATE_LIMIT_EXCEEDED') {
// Retry avec backoff
}
}
Retry Logic
Pour les erreurs temporaires (429, 500, 503), implémentez un retry avec backoff exponentiel :
async function retryRequest(fn, maxRetries = 3) {
for (let i = 0; i < maxRetries; i++) {
try {
return await fn();
} catch (error) {
if (error.status === 429 || error.status >= 500) {
const delay = Math.pow(2, i) * 1000; // 1s, 2s, 4s
await new Promise(resolve => setTimeout(resolve, delay));
} else {
throw error; // Erreur non-retriable
}
}
}
throw new Error('Max retries exceeded');
}