Erreurs

Une erreur a un vrai code HTTP et un corps application/problem+json au format de la RFC 9457 :

{
  "type": "https://docs.vizalia.ai/errors/invalid_phone",
  "title": "Numéro de téléphone invalide",
  "status": 422,
  "detail": "Le numéro doit être au format E.164, par exemple +33612345678.",
  "instance": "/v1/sessions",
  "code": "invalid_phone",
  "param": "to",
  "request_id": "req_01JC3W9A2B7K"
}

Testez code dans votre code : il est stable, comme type, qui se termine par lui et mène à la page de l’erreur. title et detail sont faits pour être lus : ils suivent Accept-Language (français par défaut, anglais avec en) et peuvent changer. request_id, repris dans l’en-tête X-Request-Id, est à donner au support.

Tous les codes

Chaque code a sa page, à l’adresse que donne le champ type de l’erreur.

• Une route ou une méthode inconnue répond 404 not_found, en application/problem+json, jamais 405.
• Un champ inconnu, une valeur hors bornes ou une action inconnue répondent 400 invalid_request, avec param : par exemple une Idempotency-Key de plus de 255 caractères, un message de plus de 108 ou plus de 20 paires metadata. Un champ inconnu est refusé, pas ignoré.

HTTP	code	Que faire
400	invalid_request	Corriger la requête : JSON illisible, paramètre inconnu ou mal formé.
401	unauthorized	Vérifier la clé : absente, inconnue, révoquée ou expirée.
403	insufficient_scope	Donner à la clé la portée qui manque.
403	test_mode_only	Utiliser une clé de test : simulate n'existe qu'en mode test.
403	report_download_disabled	Rien à corriger : l'espace interdit le téléchargement du rapport.
404	not_found	Vérifier l'identifiant : ressource inconnue ou d'un autre espace.
409	idempotency_conflict	Même Idempotency-Key avec un autre corps : changer de clé.
409	session_ended	La session est terminée : en créer une autre.
409	report_not_ready	Attendre le webhook report.ready.
422	phone_required	Corriger le destinataire.
422	invalid_phone	Corriger le destinataire.
422	invalid_email	Corriger le destinataire.
422	channel_disabled	Choisir une valeur active de l'espace ; param dit laquelle.
422	unknown_brand	Choisir une valeur active de l'espace ; param dit laquelle.
422	unknown_advisor	Choisir une valeur active de l'espace ; param dit laquelle.
422	unknown_scenario	Choisir une valeur active de l'espace ; param dit laquelle.
422	invalid_report_options	Corriger l'option ou l'URL désignée par param.
422	invalid_webhook_url	Corriger l'option ou l'URL désignée par param.
429	quota_exceeded	Réessayer après Retry-After secondes.
500	internal_error	Réessayer plus tard ; donner request_id au support.
503	report_renderer_unavailable	Réessayer après Retry-After secondes.
503	report_attachment_unavailable	Réessayer après Retry-After secondes.

Dans votre code

Branchez-vous sur le statut HTTP pour la famille d’erreur, et sur code pour la cause précise. Réessayez seulement ce qui peut l’être : 429 et 503 après Retry-After secondes, 500 plus tard, et une requête rejouée garde son Idempotency-Key.

Node.js

const reponse = await fetch('https://api.vizalia.ai/v1/sessions', requete);
if (!reponse.ok) {
  const type = reponse.headers.get('content-type') ?? '';
  const erreur = type.includes('json') ? await reponse.json() : { code: null };
  switch (erreur.code) {
    case 'invalid_phone':
      // Le numéro saisi est refusé : `param` nomme le champ, `detail` s'affiche tel quel.
      return demanderUnAutreNumero(erreur.detail);
    case 'quota_exceeded':
      return reessayerDans(Number(reponse.headers.get('retry-after') ?? 60));
    default:
      throw new Error(`${reponse.status} ${erreur.code} (${erreur.request_id})`);
  }
}

Python

reponse = requests.post("https://api.vizalia.ai/v1/sessions", json=corps, headers=entetes, timeout=30)
if not reponse.ok:
    erreur = reponse.json() if "json" in reponse.headers.get("content-type", "") else {}
    code = erreur.get("code")
    if code == "invalid_phone":
        # Le numéro saisi est refusé : `param` nomme le champ, `detail` s'affiche tel quel.
        return demander_un_autre_numero(erreur["detail"])
    if code == "quota_exceeded":
        return reessayer_dans(int(reponse.headers.get("Retry-After", 60)))
    raise RuntimeError(f"{reponse.status_code} {code} ({erreur.get('request_id')})")