Errors

Catch PotatoApiError for failed HTTP responses and polling timeouts. Network errors, credential callback errors, and local argument errors can be other error types. This example calls client.me() using the client.ts module from the quickstart.

import { PotatoApiError } from "@toloka-platform/sdk";
import { client } from "./client";

try {
  await client.me();
} catch (error) {
  if (!(error instanceof PotatoApiError)) throw error;

  console.error(error.message);
  console.error("HTTP status:", error.status);
  console.error("Response body:", error.body);
  console.error("Request ID:", error.requestId);
}

PotatoApiError

Property	HTTP failure	Wait timeout
`code`	`"http"`	`"wait_timeout"`
`status`	HTTP status number	`undefined`
`body`	Parsed JSON, response text, or `undefined` for an empty body	`{ timeoutMs: number }`
`requestId`	`X-Request-Id`, when present	`undefined`
`message`	`Potato API request failed with status <status>`, followed by `(request id: <id>)` when available	`Potato API job did not reach a terminal status within <timeoutMs> ms`

The HTTP message does not include the response body. Inspect body, whose type is unknown, for the platform’s explanation. Quote requestId when reporting a failed request.

Respond to HTTP failures

Status	Next action
`400`	Correct the request using the response body and the operation’s parameter schema.
`401`	Check the credential and platform URL; replace an expired or revoked token.
`403`	Check permissions, token scope, and any required account verification.
`404`	Check the resource ID and the credential’s project and team access.
`409`	Read the resource again and resolve the state or version conflict before retrying.
`429`	Reduce request frequency and wait before retrying; for a live-token cap, revoke unused tokens.
`5xx`	Inspect the resource before repeating a write, since it may have taken effect. Retry a safe read with backoff and retain the request ID if failures continue.

Use HTTP API troubleshooting for specific messages, and client request behavior for rate-limit handling.

Handle a wait timeout

Set TOLOKA_EXPORT_ID to the export ID returned by datasets.startExport in the quickstart. This resumes waiting for that export. A timeout stops polling but leaves the job running; retain the ID to check it again.

import { PotatoApiError } from "@toloka-platform/sdk";
import { client } from "./client";

const exportId = process.env.TOLOKA_EXPORT_ID;
if (!exportId) throw new Error("Set TOLOKA_EXPORT_ID to the export ID from the earlier step");

try {
  const job = await client.waitFor(
    { type: "datasetExport", exportId },
    { timeoutMs: 120_000, intervalMs: 2_000 },
  );
  if (job.status === "failed") {
    console.error(job.error?.code, job.error?.message);
  } else {
    console.log(job.result.downloadUrl);
  }
} catch (error) {
  if (!(error instanceof PotatoApiError) || error.code !== "wait_timeout") throw error;
  console.error("Stopped waiting for export:", exportId, error.body);
}

PipelineGraphValidationError

validate(graph) throws PipelineGraphValidationError when a graph fails the local graph schema or supported entity checks. It exposes code: "invalid_pipeline_graph" and issues, an array of { path, reason }. Its message starts with Pipeline graph validation failed and lists the issues. validatePipelineDefinition and resolvePipelineDefinition also call validate. The CLI loads pipeline source through validatePipelineDefinition, so the same error can surface when loading a project.

import { readFile } from "node:fs/promises";
import { PipelineGraphValidationError, validate } from "@toloka-platform/sdk";

const graph: unknown = JSON.parse(await readFile("graph.json", "utf8"));

try {
  validate(graph);
  console.log("Graph version:", graph.version);
} catch (error) {
  if (!(error instanceof PipelineGraphValidationError)) throw error;
  for (const issue of error.issues) {
    console.error(issue.path, issue.reason);
  }
}

Authoring helpers also perform argument checks. For example, duplicate IDs in definePipeline and invalid condition names in match throw ordinary errors. A graph rejected by an HTTP write is a PotatoApiError; local validation errors do not represent an HTTP response.

TypeScript SDK

Pipelines as code

CLI

PotatoApiError

Respond to HTTP failures

Handle a wait timeout

PipelineGraphValidationError

​PotatoApiError

​Respond to HTTP failures

​Handle a wait timeout

​PipelineGraphValidationError

PotatoApiError

Respond to HTTP failures

Handle a wait timeout

PipelineGraphValidationError