Erreurs

Le SDK expose deux classes d’erreurs : YoukaRequestError pour les erreurs HTTP et de validation, et YoukaTaskError pour les tâches asynchrones qui se terminent dans un état non réussi. Les deux étendent Error et embarquent des champs structurés afin que vous puissiez brancher sur le code, le statut et la possibilité de retenter.

`YoukaRequestError`

Levée pour les erreurs HTTP, les échecs de validation de requête et les réponses malformées.

import { YoukaRequestError } from "@youka/sdk";

try {
  await client.projects.create(body);
} catch (error) {
  if (error instanceof YoukaRequestError) {
    console.error({
      code: error.code,
      message: error.message,
      status: error.status,
      retryable: error.retryable,
      details: error.details,
    });
  } else {
    throw error;
  }
}

Champs

string

Code d’erreur lisible par machine, par exemple INVALID_REQUEST, UNAUTHORIZED, UPLOAD_FAILED.

string

Description lisible par l’humain.

number

Code de statut HTTP, si disponible.

boolean

true si le SDK considère que l’erreur mérite d’être retentée (limites de débit, erreurs serveur transitoires, relecture idempotente en cours).

unknown

Détails fournis par le serveur, généralement une liste d’issues Zod pour les erreurs de validation.

Codes courants

Code	Cause	Retentable ?
`INVALID_REQUEST`	Le corps de la requête n’a pas passé la validation du schéma avant l’envoi.	Non
`UNAUTHORIZED`	Clé API manquante ou invalide.	Non
`NOT_FOUND`	La ressource n’existe pas ou vous n’y avez pas accès.	Non
`CONFLICT`	Conflit de version (HTTP 409).	Oui
`TOO_MANY_REQUESTS`	Limite de débit atteinte (HTTP 429).	Oui
`INTERNAL_SERVER_ERROR`	Panne serveur transitoire (HTTP 500).	Oui
`IDEMPOTENT_REPLAY_IN_PROGRESS`	La requête d’origine est toujours en cours avec la même clé d’idempotence (HTTP 202).	Oui
`INVALID_RESPONSE`	Le serveur a renvoyé un corps qui ne correspondait pas au schéma attendu.	Non
`UPLOAD_FAILED`	L’upload via l’URL signée a renvoyé un statut non-2xx.	Dépend du statut

`YoukaTaskError`

Levée depuis client.tasks.wait(...), client.projects.wait(...) et client.exports.wait(...) lorsque la tâche ou l’export sous-jacent se termine en failed, cancelled ou timed-out.

import { YoukaTaskError } from "@youka/sdk";

try {
  await client.projects.wait(created);
} catch (error) {
  if (error instanceof YoukaTaskError) {
    console.error({
      code: error.code,
      message: error.message,
      status: error.status,
      task: error.task,
    });
  } else {
    throw error;
  }
}

Champs

'TASK_FAILED' | 'TASK_CANCELLED' | 'TASK_TIMED_OUT'

Correspond directement au statut terminal de la tâche.

string

Soit le message d’erreur de la tâche fourni par le serveur, soit un message de repli généré.

TaskStatus

Le statut terminal de la tâche.

RestTask

La charge utile complète de la tâche au moment de l’échec. Utile pour la journalisation et les messages d’erreur destinés à l’utilisateur.

Modèle de retry

Combinez retryable avec une clé d’idempotence pour construire une boucle de retry sûre :

import { YoukaRequestError } from "@youka/sdk";

async function createWithRetry<T>(fn: () => Promise<T>, maxAttempts = 3) {
  let lastError: unknown;

  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
    try {
      return await fn();
    } catch (error) {
      lastError = error;
      if (
        error instanceof YoukaRequestError &&
        error.retryable &&
        attempt < maxAttempts
      ) {
        await new Promise((r) => setTimeout(r, 2 ** attempt * 1_000));
        continue;
      }
      throw error;
    }
  }

  throw lastError;
}

await createWithRetry(() =>
  client.projects.create(body, {
    idempotencyKey: "import-2026-04-08-song-001",
  }),
);

Réutilisez toujours la même clé d’idempotence lors des retries. Sinon le serveur traite le retry comme une nouvelle requête et vous risquez d’obtenir des doublons.

Abandon et annulation

L’abandon d’une requête lève un AbortError standard — pas un YoukaRequestError. Vérifiez-le explicitement :

try {
  await client.projects.wait(created, { signal: controller.signal });
} catch (error) {
  if (error instanceof Error && error.name === "AbortError") {
    console.log("Cancelled by user");
    return;
  }
  throw error;
}

Et ensuite

Tâches — helpers d’attente et polling avancé des tâches
Authentification — options du constructeur et signaux
Erreurs d’API — les mêmes codes en HTTP brut

Overview

How To

Customization

Audio

Settings

Exporting

Account

`YoukaRequestError`

Champs

Codes courants

`YoukaTaskError`

Champs

Modèle de retry

Abandon et annulation

Et ensuite

​YoukaRequestError

​Champs

​Codes courants

​YoukaTaskError

​Champs

​Modèle de retry

​Abandon et annulation

​Et ensuite

`YoukaRequestError`

Champs

Codes courants

`YoukaTaskError`

Champs

Modèle de retry

Abandon et annulation

Et ensuite