Erros

O SDK expõe duas classes de erro: YoukaRequestError para falhas de HTTP e validação, e YoukaTaskError para tarefas assíncronas que terminaram em um estado não bem-sucedido. Ambas estendem Error e carregam campos estruturados para que você possa ramificar por código, status e possibilidade de retry.

`YoukaRequestError`

Lançado para erros HTTP, falhas de validação de requisição e respostas malformadas.

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;
  }
}

Campos

string

Código de erro legível por máquina, por exemplo INVALID_REQUEST, UNAUTHORIZED, UPLOAD_FAILED.

string

Descrição legível por humanos.

number

Código de status HTTP, se disponível.

boolean

true se o SDK considerar que vale a pena tentar novamente (limites de taxa, erros transitórios de servidor, repetição idempotente em andamento).

unknown

Detalhes fornecidos pelo servidor, normalmente uma lista de issues do Zod para erros de validação.

Códigos comuns

Código	Causa	Retryable?
`INVALID_REQUEST`	O corpo da requisição falhou na validação do schema antes de ser enviado.	Não
`UNAUTHORIZED`	Chave de API ausente ou inválida.	Não
`NOT_FOUND`	O recurso não existe ou você não tem acesso.	Não
`CONFLICT`	Conflito de versão (HTTP 409).	Sim
`TOO_MANY_REQUESTS`	Limite de taxa atingido (HTTP 429).	Sim
`INTERNAL_SERVER_ERROR`	Falha transitória do servidor (HTTP 500).	Sim
`IDEMPOTENT_REPLAY_IN_PROGRESS`	A requisição original ainda está em execução sob a mesma chave de idempotência (HTTP 202).	Sim
`INVALID_RESPONSE`	O servidor retornou um corpo que não correspondeu ao schema esperado.	Não
`UPLOAD_FAILED`	O upload via URL assinada retornou um status diferente de 2xx.	Depende do status

`YoukaTaskError`

Lançado a partir de client.tasks.wait(...), client.projects.wait(...) e client.exports.wait(...) quando a tarefa subjacente ou a exportação termina em 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;
  }
}

Campos

'TASK_FAILED' | 'TASK_CANCELLED' | 'TASK_TIMED_OUT'

Mapeia diretamente para o status terminal da tarefa.

string

Ou a mensagem de erro da tarefa fornecida pelo servidor, ou um fallback gerado.

TaskStatus

O status terminal da tarefa.

RestTask

O payload completo da tarefa no momento da falha. Útil para logs e mensagens de erro voltadas ao usuário.

Padrão de retry

Combine retryable com uma chave de idempotência para construir um loop de retry seguro:

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",
  }),
);

Sempre reutilize a mesma chave de idempotência em todas as tentativas. Caso contrário, o servidor trata o retry como uma nova requisição e você pode acabar com duplicatas.

Abort e cancelamento

Abortar uma requisição lança um AbortError padrão — não um YoukaRequestError. Verifique explicitamente:

try {
  await client.projects.wait(created, { signal: controller.signal });
} catch (error) {
  if (error instanceof Error && error.name === "AbortError") {
    console.log("Cancelado pelo usuário");
    return;
  }
  throw error;
}

Próximos passos

Tasks — helpers de espera e polling avançado de tasks
Authentication — opções do construtor e signals
API errors — os mesmos códigos em HTTP puro

Overview

How To

Customization

Audio

Settings

Exporting

Account

`YoukaRequestError`

Campos

Códigos comuns

`YoukaTaskError`

Campos

Padrão de retry

Abort e cancelamento

Próximos passos

​YoukaRequestError

​Campos

​Códigos comuns

​YoukaTaskError

​Campos

​Padrão de retry

​Abort e cancelamento

​Próximos passos

`YoukaRequestError`

Campos

Códigos comuns

`YoukaTaskError`

Campos

Padrão de retry

Abort e cancelamento

Próximos passos