Gestion des erreurs

L'API téo utilise les codes HTTP standards pour indiquer le succès ou l'échec d'une requête. Cette page vous aide à comprendre et résoudre les erreurs courantes.

Codes HTTP

Code	Signification	Description
200	OK	La requête a réussi
201	Created	La ressource a été créée avec succès
204	No Content	Succès sans contenu (suppression)
400	Bad Request	Requête mal formée ou données invalides
401	Unauthorized	Token manquant, expiré ou invalide
403	Forbidden	Accès refusé à cette ressource
404	Not Found	Ressource introuvable
422	Unprocessable Entity	Données valides mais traitement impossible
429	Too Many Requests	Limite de requêtes atteinte
500	Internal Server Error	Erreur côté serveur

Format des erreurs

Les erreurs sont retournées au format JSON-LD avec des détails sur le problème :

{
  "@context": "/api/contexts/Error",
  "@type": "hydra:Error",
  "hydra:title": "An error occurred",
  "hydra:description": "Description détaillée de l'erreur",
  "violations": [
    {
      "propertyPath": "email",
      "message": "Cette valeur n'est pas une adresse email valide."
    }
  ]
}

Erreurs d'authentification (401)

Token manquant

Symptôme : "No authorization header found"

Solution : Ajoutez l'en-tête Authorization à votre requête :

curl -H "Authorization: Bearer VOTRE_TOKEN" https://teoapp.fr/api/...

Token expiré

Symptôme : "Expired token" ou "Token has expired"

Solution : Obtenez un nouveau token. Les tokens expirent après 10 minutes.

// Exemple de renouvellement automatique
async function getToken() {
  if (!token || isExpired(token)) {
    token = await refreshToken();
  }
  return token;
}

Token invalide

Symptôme : "Invalid token" ou "Signature verification failed"

Causes possibles :

• Le token a été mal copié (caractères manquants)
• Vous utilisez un token d'un autre environnement
• Le token a été révoqué

Solution : Générez un nouveau token avec les bons identifiants.

Erreurs de validation (400/422)

Données manquantes

Symptôme : "This value should not be blank"

{
  "violations": [
    {
      "propertyPath": "firstName",
      "message": "Cette valeur ne doit pas être vide."
    }
  ]
}

Solution : Vérifiez que tous les champs obligatoires sont renseignés.

Format invalide

Symptôme : "This value is not valid"

Exemples courants :

• Email mal formaté
• Date dans un format incorrect
• UUID invalide

{
  "violations": [
    {
      "propertyPath": "email",
      "message": "Cette valeur n'est pas une adresse email valide."
    }
  ]
}

Solution : Vérifiez le format des données envoyées. Consultez la référence API pour les formats attendus.

Valeur non autorisée

Symptôme : "The value you selected is not a valid choice"

{
  "violations": [
    {
      "propertyPath": "status",
      "message": "La valeur sélectionnée n'est pas un choix valide."
    }
  ]
}

Solution : Utilisez une valeur parmi celles autorisées. Consultez le manuel de référence de l'API pour les valeurs possibles.

Erreurs d'accès (403)

Ressource non accessible

Symptôme : "Access Denied"

Causes possibles :

• Votre token n'a pas les droits sur cette ressource
• La ressource appartient à un autre téo
• Votre compte n'a pas les permissions nécessaires

Solution : Vérifiez que :

1. Vous utilisez le bon TEO_ID dans le scope
2. La ressource existe dans votre périmètre
3. Votre compte a les droits appropriés

Erreurs de ressource (404)

Ressource introuvable

Symptôme : "Not Found" ou "No route found"

Causes possibles :

• L'UUID est incorrect
• La ressource a été supprimée
• L'endpoint n'existe pas

Solution :

# Vérifiez que l'endpoint existe
curl https://teoapp.fr/api/docs

# Vérifiez l'UUID
curl https://teoapp.fr/api/production/dossiers/UUID_CORRECT

Limite de requêtes (429)

Trop de requêtes

Symptôme : "Too Many Requests" avec un header Retry-After

Solution : Implémentez un système de retry avec backoff exponentiel :

async function fetchWithRetry(url, options, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    const response = await fetch(url, options);
    
    if (response.status === 429) {
      const retryAfter = response.headers.get('Retry-After') || 60;
      await sleep(retryAfter * 1000);
      continue;
    }
    
    return response;
  }
  throw new Error('Max retries exceeded');
}

Bonnes pratiques

• Mettez en cache les données qui changent peu
• Utilisez la pagination plutôt que de tout récupérer
• Espacez vos requêtes en cas de traitement batch

Erreurs serveur (500)

Erreur interne

Symptôme : "Internal Server Error"

Solution :

1. Réessayez dans quelques instants
2. Si le problème persiste, contactez le support
3. Incluez dans votre ticket :
   • L'endpoint appelé
   • Les données envoyées (sans informations sensibles)
   • L'heure exacte de l'erreur
   • L'ID de corrélation si présent dans la réponse

Debugging

Activer les logs

Loggez toutes vos requêtes et réponses pour faciliter le debug :

async function apiCall(endpoint, options = {}) {
  console.log(`[API] ${options.method || 'GET'} ${endpoint}`);
  
  const response = await fetch(`https://teoapp.fr/api${endpoint}`, {
    ...options,
    headers: {
      'Authorization': `Bearer ${token}`,
      'Accept': 'application/ld+json',
      ...options.headers
    }
  });
  
  const data = await response.json();
  
  if (!response.ok) {
    console.error(`[API] Error ${response.status}:`, data);
    throw new ApiError(response.status, data);
  }
  
  return data;
}

Vérifier votre token

Décodez votre token JWT pour vérifier son contenu :

# Le payload est la partie centrale (entre les deux points)
echo "VOTRE_TOKEN" | cut -d'.' -f2 | base64 -d | jq

Vérifiez notamment :

• exp : timestamp d'expiration (doit être dans le futur)
• scope : doit contenir votre TEO_ID

FAQ

Mon token fonctionne une fois puis échoue

Vérifiez que vous ne créez pas un nouveau token à chaque requête. Réutilisez le même token jusqu'à son expiration.

J'obtiens 403 sur une ressource que je viens de créer

Il peut y avoir un léger délai de propagation. Attendez quelques secondes et réessayez.

Les accents ne s'affichent pas correctement

Assurez-vous d'envoyer et recevoir en UTF-8 :

curl -H "Content-Type: application/json; charset=utf-8" ...

Comment tester sans données de production ?

Utilisez l'environnement sandbox. Contactez le support pour obtenir un accès.