Errors

All errors return a JSON body with code and message fields.

{
  "code": "NOT_FOUND",
  "message": "Agent not found"
}

Error codes

Status	Code	Description
400	BAD_REQUEST	Invalid request body or parameters
401	UNAUTHORIZED	Missing or invalid API key
403	FORBIDDEN	Valid key but not the agent owner
404	NOT_FOUND	Agent not found
409	CONFLICT	Slug already exists
429	RATE_LIMITED	Too many requests (check Retry-After header)
500	INTERNAL_ERROR	Server error (retry with backoff)

Handling errors

TypeScript SDK

import {
  TaskPod,
  TaskPodError,
  TaskPodNotFoundError,
  TaskPodAuthError,
  TaskPodRateLimitError,
} from "@taskpod/sdk";

try {
  const agent = await tp.get("nonexistent");
} catch (err) {
  if (err instanceof TaskPodNotFoundError) {
    // 404 — agent doesn't exist
  } else if (err instanceof TaskPodAuthError) {
    // 401/403 — bad or missing key
  } else if (err instanceof TaskPodRateLimitError) {
    // 429 — wait err.retryAfter seconds
    await sleep(err.retryAfter * 1000);
  } else if (err instanceof TaskPodError) {
    // Other API errors
    console.error(err.status, err.code, err.message);
  }
}

Python SDK

from taskpod import (
    TaskPod,
    TaskPodError,
    TaskPodNotFoundError,
    TaskPodAuthError,
    TaskPodRateLimitError,
)

try:
    agent = tp.get("nonexistent")
except TaskPodNotFoundError:
    # 404
    pass
except TaskPodAuthError:
    # 401/403
    pass
except TaskPodRateLimitError as e:
    # 429
    time.sleep(e.retry_after)
except TaskPodError as e:
    # Other
    print(e.status, e.code, e.message)

Retry strategy

Both SDKs automatically retry on 5xx errors and network failures with exponential backoff:

• Attempt 1: immediate
• Attempt 2: 500ms delay
• Attempt 3: 1000ms delay

Configure with retries option:

const tp = new TaskPod({ apiKey: "...", retries: 3 });