Référence des erreurs API

Ce guide documente tous les codes d’erreur, formats de réponse et étapes de dépannage pour l’API TeamDay.

---

Format de réponse d’erreur

Toutes les erreurs API suivent une structure JSON cohérente :

{
  "error": true,
  "statusCode": 400,
  "statusMessage": "Bad Request",
  "message": "Description détaillée de l'erreur"
}

Champs :

• error (booléen) - Toujours true pour les réponses d’erreur
• statusCode (nombre) - Code de statut HTTP
• statusMessage (chaîne) - Statut lisible par l’homme
• message (chaîne) - Explication détaillée de l’erreur

---

Codes de statut HTTP

2xx Succès

Ce ne sont pas des erreurs, mais des réponses réussies :

200 OK

Signification : La requête a réussi

Utilisé par :

• Requêtes GET (liste, obtenir les détails)
• Requêtes PATCH (mise à jour)
• Requêtes DELETE (suppression logique)
• Requêtes POST (annuler l’exécution)

Exemple :

{
  "id": "agent_abc123",
  "name": "Assistant de recherche",
  "...": "..."
}

201 Created

Signification : Ressource créée avec succès

Utilisé par :

• Requêtes POST (créer agent, tâche)

Exemple :

{
  "id": "agent_abc123",
  "name": "Assistant de recherche",
  "createdAt": "2025-12-09T10:00:00Z",
  "...": "..."
}

---

4xx Erreurs client

Ces erreurs indiquent des problèmes avec la requête.

400 Bad Request

Signification : Paramètres de requête invalides ou champs requis manquants

Causes courantes :

• Champs requis manquants
• Valeurs de champs invalides
• JSON mal formé
• Paramètres de requête invalides

Exemples :

Champ requis manquant :

{
  "error": true,
  "statusCode": 400,
  "statusMessage": "Bad Request",
  "message": "Missing required field: name"
}

Valeur de visibilité invalide :

{
  "error": true,
  "statusCode": 400,
  "statusMessage": "Bad Request",
  "message": "Invalid visibility value. Must be: private, organization, or public"
}

Statut invalide :

{
  "error": true,
  "statusCode": 400,
  "statusMessage": "Bad Request",
  "message": "Invalid status. Must be: pending, in_progress, completed, cancelled"
}

JSON mal formé :

{
  "error": true,
  "statusCode": 400,
  "statusMessage": "Bad Request",
  "message": "Invalid JSON in request body"
}

Comment corriger :

1. Vérifier que le corps de la requête correspond à la documentation de l’API
2. Valider que tous les champs requis sont présents
3. Vérifier que les valeurs des champs sont valides (énumérations, types)
4. Tester la syntaxe JSON avec un validateur

---

401 Unauthorized

Signification : Authentification échouée ou manquante

Causes courantes :

• En-tête Authorization manquant
• Jeton invalide
• Jeton expiré
• Format de jeton incorrect

Exemples :

En-tête manquant :

{
  "error": true,
  "statusCode": 401,
  "statusMessage": "Unauthorized",
  "message": "Authorization header required"
}

Jeton invalide :

{
  "error": true,
  "statusCode": 401,
  "statusMessage": "Unauthorized",
  "message": "Invalid or expired token"
}

Jeton expiré :

{
  "error": true,
  "statusCode": 401,
  "statusMessage": "Unauthorized",
  "message": "Token expired"
}

Mauvais format :

{
  "error": true,
  "statusCode": 401,
  "statusMessage": "Unauthorized",
  "message": "Token must start with 'td_'"
}

Comment corriger :

1. Vérifier que l’en-tête Authorization est présent
2. Vérifier le format de l’en-tête : Authorization: Bearer td_xxxxx...
3. Confirmer que le jeton n’est pas expiré dans Paramètres → Accès API
4. Générer un nouveau jeton si nécessaire
5. Vérifier que le jeton est copié correctement (pas d’espaces supplémentaires)

---

403 Forbidden

Signification : Authentifié mais non autorisé pour cette action

Causes courantes :

• L’utilisateur n’a pas les permissions requises
• Accès à l’organisation révoqué
• La ressource appartient à une autre organisation

Exemple :

{
  "error": true,
  "statusCode": 403,
  "statusMessage": "Forbidden",
  "message": "You don't have permission to access this resource"
}

Comment corriger :

1. Vérifier que l’utilisateur a le rôle/permissions corrects
2. Vérifier que l’utilisateur appartient toujours à l’organisation
3. Confirmer que la ressource appartient à votre organisation
4. Contacter l’administrateur de l’organisation pour les changements de permissions

---

404 Not Found

Signification : La ressource n’existe pas

Causes courantes :

• ID de ressource invalide
• La ressource a été supprimée
• La ressource appartient à une autre organisation
• Faute de frappe dans l’URL de l’endpoint

Exemples :

Agent non trouvé :

{
  "error": true,
  "statusCode": 404,
  "statusMessage": "Not Found",
  "message": "Agent not found"
}

Exécution non trouvée :

{
  "error": true,
  "statusCode": 404,
  "statusMessage": "Not Found",
  "message": "Execution not found"
}

Tâche non trouvée :

{
  "error": true,
  "statusCode": 404,
  "statusMessage": "Not Found",
  "message": "Task not found"
}

Comment corriger :

1. Vérifier que l’ID de la ressource est correct
2. Vérifier que la ressource n’a pas été supprimée
3. Confirmer que la ressource appartient à votre organisation
4. Lister les ressources pour trouver l’ID correct
5. Vérifier les fautes de frappe dans l’URL

---

429 Too Many Requests

Signification : Limite de débit dépassée

Statut : Pas actuellement appliqué, mais pourrait l’être à l’avenir

Exemple :

{
  "error": true,
  "statusCode": 429,
  "statusMessage": "Too Many Requests",
  "message": "Rate limit exceeded. Retry after 60 seconds."
}

Comment corriger :

1. Implémenter un backoff exponentiel
2. Réduire la fréquence des requêtes
3. Mettre en cache les réponses si possible
4. Contacter le support pour des limites plus élevées

---

5xx Erreurs serveur

Ces erreurs indiquent des problèmes côté serveur.

500 Internal Server Error

Signification : Erreur serveur inattendue

Causes courantes :

• Problèmes de connectivité de base de données
• Échec de dépendance de service
• Exception non gérée
• Erreur de configuration

Exemple :

{
  "error": true,
  "statusCode": 500,
  "statusMessage": "Internal Server Error",
  "message": "An unexpected error occurred"
}

Problèmes connus :

Exécution d’agent cassée :

{
  "error": true,
  "statusCode": 500,
  "statusMessage": "Internal Server Error",
  "message": "Chat execution failed"
}

Cause : Problème avec l’endpoint interne /api/claude-code/chat

Solution de contournement : Utiliser l’interface web pour l’exécution d’agents

Comment corriger :

1. Réessayer la requête (peut être transitoire)
2. Vérifier la page de statut de l’API
3. Attendre quelques minutes et réessayer
4. Contacter le support si le problème persiste
5. Vérifier les problèmes connus dans la documentation

---

503 Service Unavailable

Signification : Service temporairement indisponible

Causes courantes :

• Maintenance planifiée
• Surcharge du système
• Service de dépendance hors ligne

Exemple :

{
  "error": true,
  "statusCode": 503,
  "statusMessage": "Service Unavailable",
  "message": "Service temporarily unavailable. Please retry."
}

Comment corriger :

1. Attendre et réessayer avec un backoff exponentiel
2. Vérifier la page de statut pour les fenêtres de maintenance
3. Contacter le support si la panne est prolongée

---

Bonnes pratiques de gestion des erreurs

1. Toujours vérifier les codes de statut

const response = await fetch('https://us.teamday.ai/api/v1/agents', {
  headers: {
    'Authorization': `Bearer ${token}`
  }
})

if (!response.ok) {
  const error = await response.json()
  console.error(`Erreur API ${error.statusCode}: ${error.message}`)
  // Gérer l'erreur de manière appropriée
}

const data = await response.json()

2. Gérer les cas d’erreur spécifiques

async function handleApiError(response) {
  const error = await response.json()

  switch (error.statusCode) {
    case 400:
      // Erreur de validation - corriger la requête
      console.error('Requête invalide:', error.message)
      break

    case 401:
      // Erreur d'authentification - rafraîchir le jeton ou se réauthentifier
      console.error('Échec de l\'authentification:', error.message)
      await refreshToken()
      break

    case 404:
      // Non trouvé - la ressource n'existe pas
      console.error('Ressource non trouvée:', error.message)
      break

    case 500:
      // Erreur serveur - réessayer avec backoff
      console.error('Erreur serveur:', error.message)
      await retryWithBackoff()
      break

    default:
      console.error('Erreur inattendue:', error)
  }
}

3. Implémenter une logique de nouvelle tentative

async function fetchWithRetry(url, options, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      const response = await fetch(url, options)

      if (response.ok) {
        return await response.json()
      }

      const error = await response.json()

      // Ne pas réessayer les erreurs client (4xx)
      if (error.statusCode >= 400 && error.statusCode < 500) {
        throw new Error(error.message)
      }

      // Réessayer les erreurs serveur (5xx) avec backoff exponentiel
      if (i < maxRetries - 1) {
        const delay = Math.pow(2, i) * 1000 // 1s, 2s, 4s
        console.log(`Nouvelle tentative dans ${delay}ms...`)
        await new Promise(resolve => setTimeout(resolve, delay))
        continue
      }

      throw new Error(error.message)

    } catch (err) {
      if (i === maxRetries - 1) throw err
    }
  }
}

4. Logger les erreurs de manière appropriée

async function makeApiRequest(endpoint, options) {
  try {
    const response = await fetch(endpoint, options)

    if (!response.ok) {
      const error = await response.json()

      // Logger les détails de l'erreur (mais pas les données sensibles)
      console.error('Erreur API:', {
        endpoint,
        statusCode: error.statusCode,
        message: error.message,
        timestamp: new Date().toISOString()
        // Ne pas logger : jetons, mots de passe, PII
      })

      throw error
    }

    return await response.json()

  } catch (err) {
    // Logger l'exception
    console.error('Échec de la requête:', {
      endpoint,
      error: err.message,
      timestamp: new Date().toISOString()
    })

    throw err
  }
}

5. Fournir des messages conviviaux

function getUserFriendlyError(apiError) {
  const messages = {
    400: 'Requête invalide. Veuillez vérifier votre saisie.',
    401: 'Échec de l\'authentification. Veuillez vous reconnecter.',
    403: 'Vous n\'avez pas la permission d\'effectuer cette action.',
    404: 'La ressource demandée n\'a pas été trouvée.',
    429: 'Trop de requêtes. Veuillez réessayer plus tard.',
    500: 'Erreur serveur. Veuillez réessayer.',
    503: 'Service temporairement indisponible. Veuillez réessayer bientôt.'
  }

  return messages[apiError.statusCode] || 'Une erreur inattendue s\'est produite.'
}

// Utilisation
try {
  const data = await createAgent(agentData)
} catch (err) {
  const userMessage = getUserFriendlyError(err)
  showErrorToUser(userMessage)
}

---

Scénarios d’erreur courants

Scénario 1 : Jeton expiré

Erreur :

{
  "statusCode": 401,
  "message": "Token expired"
}

Solution :

async function ensureValidToken() {
  try {
    // Tester le jeton
    const response = await fetch('https://us.teamday.ai/api/v1/agents', {
      headers: { 'Authorization': `Bearer ${token}` }
    })

    if (response.status === 401) {
      console.log('Jeton expiré, génération d\'un nouveau...')
      // Rediriger vers le tableau de bord pour générer un nouveau jeton
      window.location.href = 'https://us.teamday.ai/settings/api'
    }

  } catch (err) {
    console.error('Échec de la validation du jeton:', err)
  }
}

---

Scénario 2 : Champ requis manquant

Erreur :

{
  "statusCode": 400,
  "message": "Missing required field: name"
}

Solution :

async function createAgent(agentData) {
  // Valider les champs requis avant l'appel API
  const required = ['name', 'systemPrompt']

  for (const field of required) {
    if (!agentData[field]) {
      throw new Error(`Champ requis manquant : ${field}`)
    }
  }

  // Faire l'appel API
  const response = await fetch('https://us.teamday.ai/api/v1/agents', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${token}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify(agentData)
  })

  if (!response.ok) {
    const error = await response.json()
    throw error
  }

  return await response.json()
}

---

Scénario 3 : Agent non trouvé

Erreur :

{
  "statusCode": 404,
  "message": "Agent not found"
}

Solution :

async function getAgentSafely(agentId) {
  try {
    const response = await fetch(
      `https://us.teamday.ai/api/v1/agents/${agentId}`,
      {
        headers: { 'Authorization': `Bearer ${token}` }
      }
    )

    if (response.status === 404) {
      console.log(`Agent ${agentId} non trouvé. Peut-être supprimé.`)
      return null
    }

    if (!response.ok) {
      throw await response.json()
    }

    return await response.json()

  } catch (err) {
    console.error('Échec de récupération de l\'agent:', err)
    return null
  }
}

---

Scénario 4 : Erreur serveur (500)

Erreur :

{
  "statusCode": 500,
  "message": "Internal server error"
}

Solution :

async function createAgentWithRetry(agentData) {
  const maxRetries = 3

  for (let i = 0; i < maxRetries; i++) {
    try {
      const response = await fetch('https://us.teamday.ai/api/v1/agents', {
        method: 'POST',
        headers: {
          'Authorization': `Bearer ${token}`,
          'Content-Type': 'application/json'
        },
        body: JSON.stringify(agentData)
      })

      if (response.ok) {
        return await response.json()
      }

      const error = await response.json()

      // Réessayer uniquement les erreurs serveur
      if (error.statusCode >= 500 && i < maxRetries - 1) {
        const delay = Math.pow(2, i) * 1000
        console.log(`Erreur serveur. Nouvelle tentative dans ${delay}ms...`)
        await new Promise(resolve => setTimeout(resolve, delay))
        continue
      }

      throw error

    } catch (err) {
      if (i === maxRetries - 1) {
        console.error('Toutes les tentatives ont échoué:', err)
        throw err
      }
    }
  }
}

---

Conseils de débogage

1. Vérifier les en-têtes de requête

# Utiliser curl -v pour une sortie détaillée
curl -v https://us.teamday.ai/api/v1/agents \
  -H "Authorization: Bearer $TEAMDAY_TOKEN"

# Vérifier les en-têtes envoyés

2. Valider le JSON

# Utiliser jq pour valider le JSON
echo '{
  "name": "Agent de test",
  "systemPrompt": "Vous êtes utile"
}' | jq .

# Devrait afficher le JSON formaté si valide

3. Tester l’authentification

# Test d'authentification rapide
curl https://us.teamday.ai/api/v1/agents \
  -H "Authorization: Bearer $TEAMDAY_TOKEN"

# Devrait retourner 200 avec la liste des agents (ou un tableau vide)

4. Inspecter les en-têtes de réponse

# Vérifier les en-têtes de réponse
curl -I https://us.teamday.ai/api/v1/agents \
  -H "Authorization: Bearer $TEAMDAY_TOKEN"

# Rechercher :
# - Code de statut HTTP
# - Content-Type
# - Détails de l'erreur

5. Utiliser des outils de test d’API

Outils recommandés :

• Postman - Test d’API complet
• Insomnia - Alternative légère
• curl - Test en ligne de commande
• HTTPie - Alternative conviviale à curl

Exemple Postman :

POST https://us.teamday.ai/api/v1/agents
En-têtes :
  Authorization: Bearer td_xxxxx...
  Content-Type: application/json
Corps :
  {
    "name": "Agent de test",
    "systemPrompt": "Vous êtes utile"
  }

---

Tableau de référence des erreurs

Référence rapide pour toutes les erreurs API :

Code	Message	Cause	Solution
400	Champ requis manquant	Champ requis omis	Ajouter le champ manquant
400	JSON invalide	Corps JSON mal formé	Valider la syntaxe JSON
400	Visibilité invalide	Mauvaise valeur d’énumération	Utiliser : private, organization, public
400	Statut invalide	Mauvaise valeur d’énumération	Utiliser : pending, in_progress, completed, cancelled
400	Priorité invalide	Mauvaise valeur d’énumération	Utiliser : low, medium, high, urgent
400	Impossible d’annuler	Déjà terminé	Annuler uniquement les exécutions en attente/en cours
401	En-tête d’autorisation requis	En-tête manquant	Ajouter l’en-tête Authorization
401	Jeton invalide ou expiré	Mauvais jeton	Générer un nouveau jeton
401	Jeton expiré	Jeton passé l’expiration	Générer un nouveau jeton
403	Pas de permission	Permissions insuffisantes	Vérifier le rôle de l’utilisateur
404	Agent non trouvé	ID d’agent invalide	Vérifier que l’agent existe
404	Exécution non trouvée	ID d’exécution invalide	Vérifier que l’exécution existe
404	Tâche non trouvée	ID de tâche invalide	Vérifier que la tâche existe
429	Limite de débit dépassée	Trop de requêtes	Implémenter un backoff
500	Erreur serveur interne	Problème serveur	Réessayer avec backoff
500	Échec de l’exécution du chat	Problème connu	Utiliser l’interface web
503	Service indisponible	Maintenance/surcharge	Attendre et réessayer

---

Obtenir de l’aide

Consulter la documentation

1. Aperçu de l’API - Informations générales sur l’API
2. Authentification - Configuration du jeton
3. API Agents - Endpoints des agents
4. API Exécutions - Endpoints des exécutions
5. API Tâches - Endpoints des tâches

Contacter le support

Email : support at teamday.ai

À inclure dans la demande de support :

• Message d’erreur (JSON complet)
• Détails de la requête (endpoint, méthode, en-têtes - SANS jeton)
• Étapes pour reproduire
• Comportement attendu vs. comportement réel

Exemple de demande de support :

Objet : Erreur 500 lors de la création d'un agent

J'obtiens une erreur 500 lors de la création d'un agent via l'API.

Erreur :
{
  "statusCode": 500,
  "message": "Internal server error"
}

Requête :
POST /api/v1/agents
En-têtes : Authorization: Bearer td_*****, Content-Type: application/json
Corps : {"name": "Test", "systemPrompt": "Vous êtes utile"}

Attendu : 201 Created avec objet agent
Réel : 500 Internal Server Error

J'ai essayé de réessayer 3 fois avec le même résultat.

Ressources communautaires

Discord : Rejoindre la communauté

Problèmes GitHub : Signaler des bugs

Page de statut : Vérifier les problèmes connus et la maintenance

---

Dernière mise à jour : 9 décembre 2025