Skip to main content
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

​
code
string
Código de erro legível por máquina, por exemplo INVALID_REQUEST, UNAUTHORIZED, UPLOAD_FAILED.
​
message
string
Descrição legível por humanos.
​
status
number
Código de status HTTP, se disponível.
​
retryable
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).
​
details
unknown
Detalhes fornecidos pelo servidor, normalmente uma lista de issues do Zod para erros de validação.

​
Códigos comuns

CódigoCausaRetryable?
INVALID_REQUESTO corpo da requisição falhou na validação do schema antes de ser enviado.Não
UNAUTHORIZEDChave de API ausente ou inválida.Não
NOT_FOUNDO recurso não existe ou você não tem acesso.Não
CONFLICTConflito de versão (HTTP 409).Sim
TOO_MANY_REQUESTSLimite de taxa atingido (HTTP 429).Sim
INTERNAL_SERVER_ERRORFalha transitória do servidor (HTTP 500).Sim
IDEMPOTENT_REPLAY_IN_PROGRESSA requisição original ainda está em execução sob a mesma chave de idempotência (HTTP 202).Sim
INVALID_RESPONSEO servidor retornou um corpo que não correspondeu ao schema esperado.Não
UPLOAD_FAILEDO 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

​
code
'TASK_FAILED' | 'TASK_CANCELLED' | 'TASK_TIMED_OUT'
Mapeia diretamente para o status terminal da tarefa.
​
message
string
Ou a mensagem de erro da tarefa fornecida pelo servidor, ou um fallback gerado.
​
status
TaskStatus
O status terminal da tarefa.
​
task
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