Erreurs

Requête malformée générique. Causes typiques : le corps n'est pas du JSON valide, l'en-tête Content-Type est manquant ou incorrect, des paramètres de requête contradictoires ont été envoyés (ex. limit et un flag de pagination contradictoire), ou un paramètre de chemin est malformé (non-UUID dans un slot UUID).

Vérifiez que le corps est du JSON valide (echo $body | jq . est un test rapide), confirmez que l'en-tête Content-Type: application/json est présent, et vérifiez les paramètres de chemin / requête par rapport à la référence API. Une fois le payload corrigé, réessayez.

{
  "error": "Invalid JSON body",
  "code": "bad_request",
  "request_id": "0cf409f7-382a-4c24-be9f-ae1192c38619",
  "detail": "Invalid JSON body"
}

Le corps de la requête a dépassé la limite de taille par route. Le plus courant sur les endpoints de transcription lors de l'upload audio inline (POST /transcribe) au-delà de ~10Mo. Les uploads inline sont plafonnés par conception ; les gros fichiers audio appartiennent au chemin d'upload présigné.

Pour les fichiers audio supérieurs à ~10Mo, utilisez le flux d'upload présigné : POST /uploads/presign pour obtenir une URL d'upload signée, PUT les octets directement vers cette URL, puis appelez POST /transcribe/by-upload avec l'upload_id retourné. Documenté sous Transcription.

{
  "error": "Request body too large",
  "code": "payload_too_large",
  "request_id": "0cf409f7-382a-4c24-be9f-ae1192c38619",
  "detail": "Request body too large"
}

Un champ du corps de requête ou un paramètre de requête a échoué à la validation du schéma. Le champ detail est un tableau d'objets d'erreur par champ (pas une seule chaîne), ce qui vous permet de mapper chaque entrée vers le chemin JSON exact qui a échoué. Déclencheurs courants : champ requis manquant, mauvais type, chaîne en dessous de la longueur minimale, valeur absente d'une énumération autorisée, UUID / numéro de téléphone / URL malformé.

Pour chaque entrée dans le tableau detail : loc est le chemin JSON du champ problématique (["body", "voice_id"]), msg est la raison lisible, et type est la règle de validation déclenchée (missing, string_too_short, string_pattern_mismatch, etc.). Corrigez chaque entrée, puis réessayez ; les corrections partielles déclencheront encore un 422 sur les entrées restantes.

{
  "error": "Validation failed",
  "code": "validation_error",
  "request_id": "3fddfe81-53f3-4ca1-9cea-f5fbc73ce5a2",
  "detail": [
    {
      "loc": ["body", "voice_id"],
      "msg": "Field required",
      "type": "missing"
    },
    {
      "loc": ["body", "system_prompt"],
      "msg": "String should have at least 1 character",
      "type": "string_too_short"
    }
  ],
  "fields": [
    {
      "loc": ["body", "voice_id"],
      "msg": "Field required",
      "type": "missing"
    },
    {
      "loc": ["body", "system_prompt"],
      "msg": "String should have at least 1 character",
      "type": "string_too_short"
    }
  ]
}

La ressource de chemin (agent, appel, voix, numéro de téléphone, etc.) n'existe pas sur votre compte. Note : l'accès inter-comptes renvoie également 404 (pas 403) pour éviter l'énumération des ID. Un 404 signifie donc soit que la ressource n'existe vraiment pas, soit qu'elle existe mais appartient à un autre compte.

Vérifiez l'ID en listant d'abord les ressources (GET /agents etc.) pour confirmer qu'il apparaît sur votre compte. Si vous venez de créer la ressource, attendez qu'elle soit validée ; la réponse POST est la source de vérité pour le nouvel ID. Sûr de réessayer une fois l'ID correct confirmé.

{
  "error": "Agent 'd53208ef-2f34-4be2-8bea-35cd55b399ac' not found",
  "code": "not_found",
  "request_id": "0cf409f7-382a-4c24-be9f-ae1192c38619",
  "detail": "Agent 'd53208ef-2f34-4be2-8bea-35cd55b399ac' not found"
}

La ressource est dans un état qui entre en conflit avec l'action demandée. Cas concrets : clôturer une session WebRTC déjà clôturée ("Session is not active"), réutilisation d'une clé d'idempotence avec un corps différent (protection style Stripe), ou violation d'unicité à l'enregistrement (ex. enregistrer le même numéro de téléphone deux fois).

Inspectez l'état actuel via l'endpoint GET correspondant avant de réessayer. Pour les conflits d'idempotence, générez une nouvelle clé par opération logique. Pour les conflits d'unicité, recherchez la ressource existante et décidez si vous devez la mettre à jour plutôt que la recréer. Pas sûr de réessayer aveuglément.

{
  "error": "Session is not active. The pipeline may have already ended.",
  "code": "conflict",
  "request_id": "0cf409f7-382a-4c24-be9f-ae1192c38619",
  "detail": "Session is not active. The pipeline may have already ended."
}

Votre solde de crédits a atteint zéro, le compte est en recouvrement après un échec de renouvellement, ou la carte a été refusée trop de fois et se retrouve verrouillée. Les crédits sont prépayés : à zéro, le compte est immédiatement bloqué et aucune dette ne s'accumule. Affecte uniquement les routes à l'usage : appels vocaux, sessions WebRTC, TTS, transcription. Les routes de lecture (agents, utilisation, conversations) continuent de fonctionner. Le champ code de premier niveau est un identifiant de facturation tel que billing.no_credits ou billing.payg_card_repeatedly_failed (et non le générique payment_required), et detail est un objet structuré {code, message, action_url} — utilisez le code interne pour votre gestion spécifique de la facturation.

Visitez developers.aethexai.com/dashboard/billing pour ajouter ou mettre à jour un moyen de paiement, recharger des crédits ou changer de plan. Après confirmation du nouveau paiement par Stripe, les routes à l'usage se débloquent à la prochaine requête. Consultez Facturation pour le cycle complet.

{
  "error": "Card declined on multiple retry attempts. Update your payment method to resume calls.",
  "code": "billing.payg_card_repeatedly_failed",
  "request_id": "0cf409f7-382a-4c24-be9f-ae1192c38619",
  "detail": {
    "code": "billing.payg_card_repeatedly_failed",
    "message": "Card declined on multiple retry attempts. Update your payment method to resume calls.",
    "action_url": "/dashboard/billing"
  }
}