> ## Documentation Index
> Fetch the complete documentation index at: https://docs.platform.toloka.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Errors

> Handle HTTP errors, wait timeouts, and local pipeline validation failures.

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()`](https://docs.platform.toloka.ai/docs/sdk/reference/account/me) using the `client.ts` module from the [quickstart](https://docs.platform.toloka.ai/docs/sdk/quickstart.md#2-create-a-client).

```ts theme={null}
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](https://docs.platform.toloka.ai/docs/api-reference.md#troubleshooting) for specific messages, and [client request behavior](https://docs.platform.toloka.ai/docs/sdk/client.md#rate-limits-and-retries) for rate-limit handling.

## Handle a wait timeout

Set `TOLOKA_EXPORT_ID` to the export ID returned by [`datasets.startExport`](https://docs.platform.toloka.ai/docs/sdk/reference/datasets/start-export) in the [quickstart](https://docs.platform.toloka.ai/docs/sdk/quickstart.md#5-export-and-read-the-download-link). This resumes waiting for that export. A timeout stops polling but leaves the job running; retain the ID to check it again.

```ts theme={null}
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)`](https://docs.platform.toloka.ai/docs/sdk/reference/validate) 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`](https://docs.platform.toloka.ai/docs/sdk/reference/validate) and [`resolvePipelineDefinition`](https://docs.platform.toloka.ai/docs/sdk/reference/validate) also call [`validate`](https://docs.platform.toloka.ai/docs/sdk/reference/validate). The CLI loads pipeline source through [`validatePipelineDefinition`](https://docs.platform.toloka.ai/docs/sdk/reference/validate), so the same error can surface when loading a project.

```ts theme={null}
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`](https://docs.platform.toloka.ai/docs/sdk/reference/define-pipeline) and invalid condition names in [`match`](https://docs.platform.toloka.ai/docs/sdk/reference/match) throw ordinary errors. A graph rejected by an HTTP write is a `PotatoApiError`; local validation errors do not represent an HTTP response.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.