Errors

When a request fails, Tracore returns a JSON error response with an appropriate HTTP status code.

Error response shape

{
  "error": {
    "message": "Document not found",
    "code": "DOCUMENT_NOT_FOUND",
    "details": {}
  }
}

The code and details fields are optional and may not be present on all errors.

Status codes

Status	Name	Description
`400`	Bad Request	The request body or parameters are invalid
`401`	Unauthorized	Missing or invalid API key
`403`	Forbidden	Valid API key but insufficient permissions or plan limits exceeded
`404`	Not Found	The requested resource does not exist
`409`	Conflict	The request conflicts with the current state (e.g., duplicate slug)
`429`	Rate Limited	Too many requests, retry after the indicated delay
`500`	Internal Server Error	An unexpected error occurred on the server

SDK error handling

The TypeScript SDK throws a TracoreError for non-2xx responses. You can inspect the status code and error details:

import { TracoreClient, TracoreError } from "@tracore/sdk";

const client = new TracoreClient({
  apiKey: process.env.TRACORE_API_KEY!,
});

try {
  const workspace = await client.workspaces.get("my-workspace");
} catch (error) {
  if (error instanceof TracoreError) {
    console.error(error.statusCode); // 404
    console.error(error.message); // "Workspace not found"
    console.error(error.code); // "WORKSPACE_NOT_FOUND"
  }
}

Plan limit errors

When a request is rejected due to plan limits, the response is HTTP 403 with a structured body. The code is always plan_limit_exceeded; the limit discriminator identifies which gate fired and selects the in-app paywall copy.

{
  "error": {
    "code": "plan_limit_exceeded",
    "limit": "max_pages_per_month",
    "plan": "free",
    "limitValue": 50,
    "currentValue": 50,
    "windowStart": "2026-04-01T00:00:00Z",
    "windowEnd":   "2026-05-01T00:00:00Z",
    "message": "Free plan allows 50 pages per month. Upgrade to Pro for 2,000.",
    "upgradeUrl": "/upgrade"
  }
}

`limit`	Triggered when
`max_workspaces`	Creating a workspace beyond the plan cap
`max_schemas`	Creating a schema beyond the plan cap
`max_pages_per_month`	An extraction whose pages would push you over the window total
`max_extractions_per_month`	An extraction that would exceed your monthly successful-run count
`env_not_allowed`	Targeting a non-`production` env on Free
`webhook_not_allowed`	Creating a webhook (legacy: webhooks are now allowed on every plan)
`re_extract_not_allowed`	Re-extracting an already-counted document on Free

windowStart / windowEnd are present on max_pages_per_month and max_extractions_per_month. meta is present on env_not_allowed ({ requestedEnv, allowed }). See the Plans and Limits guide for the user-facing explanation.