Errors and limits

Error response format#

All errors use the same envelope shape:

{
  "data": null,
  "error": "Human-readable error message",
  "meta": { /* optional error detail */ }
}

Status codes#

Every error response has a meta.code. When an endpoint has no more specific code, the code comes from the status: 400 invalid_request, 401 unauthorized, 402 limit_reached, 403 forbidden, 404 not_found, 405 method_not_allowed, 409 conflict, 410 gone, 422 unprocessable, 429 rate_limit_exceeded, 500 internal_error. The codes in the table below take priority.

402: Limit reached#

Returned when a write operation would exceed a count-based plan limit. The meta field contains details:

{
  "data": null,
  "error": "Limit reached: max_accounts_per_org",
  "meta": {
    "code": "limit_reached",
    "limitKey": "max_accounts_per_org",
    "current": 5,
    "max": 5
  }
}

See Plans and limits for all limit keys.

409: Already tracked#

Returned by POST /api/v2/creators, POST /api/v2/projects/{id}/creators and POST /api/v2/creators/{id}/accounts when one of the handles is already tracked in the project. Nothing is created. error names the handle and the creator that tracks it, and meta carries the ids so you can use the existing creator instead:

{
  "data": null,
  "error": "@examplecreator (TikTok) is already tracked in this project as creator \"Sam Rivera\" (3f1c…).",
  "meta": {
    "code": "already_tracked",
    "platform": "tiktok",
    "handle": "examplecreator",
    "account_id": "9a7e…",
    "creator_id": "3f1c…"
  }
}

If the same platform and handle appear twice in one request, you get 400 with meta.code: duplicate_account instead.

Idempotency-Key errors#

Write endpoints that accept an Idempotency-Key header (see Idempotency) can return:

A 5xx or 429 response is never replayed: retrying with the same key runs the request again.

404: Unknown endpoint#

A request to a path that no endpoint matches returns JSON, never the website's HTML page, so a typo'd or unsupported call can't look like a success:

{
  "data": null,
  "error": "No API endpoint matches DELETE /api/v2/goals/3f1c….",
  "meta": {
    "code": "route_not_found",
    "method": "DELETE",
    "path": "/api/v2/goals/3f1c…",
    "hint": "Check the path and method against the OpenAPI spec at /api/v2/openapi.json (docs: /docs/api-reference/overview).",
    "openapi": "/api/v2/openapi.json"
  }
}

A known path called with a method it doesn't support returns 405.

403: Insufficient scope#

Returned when a write request (POST/PATCH/DELETE) is made with a key that lacks the write scope, or an admin endpoint (org management, PIN reads, hard deletes) is called without the admin scope. A key's admin scope only counts while its owner is an org admin.

{
  "data": null,
  "error": "This action requires the 'write' scope. Granted: [read]",
  "meta": {
    "code": "insufficient_scope",
    "required": "write",
    "granted": ["read"]
  }
}

See Authentication for the scope model.

403: Insufficient role#

A key acts as one member and can never do more than they can in the app. Endpoints that only org admins can use in the app (payments and payout setup, removing creators, manual scrapes, share pages, comment settings, organization and project documents) return this when the member isn't an org admin. The OpenAPI spec marks each of them "Requires an org admin".

{
  "data": null,
  "error": "You need to be an organization admin to do this. Ask an org admin to update your role in Organization settings.",
  "meta": { "code": "insufficient_role", "required": "org_admin" }
}

Use a key that acts as an org admin, or ask an org admin to do it.

429: Rate limited#

Two separate systems can produce 429s, and both use meta.code: "rate_limit_exceeded".

Per-key sliding window: more than 60 requests per minute from a single API key. The response carries a Retry-After header (seconds). Retry after a brief delay.

{
  "data": null,
  "error": "Rate limit exceeded",
  "meta": {
    "code": "rate_limit_exceeded",
    "bucket": "v1Api",
    "retryAfter": 7
  }
}

Daily quota: your org's daily api_requests allowance was exhausted. Resets at midnight in your org's time zone. Like the per-key limiter, this response carries a Retry-After header (seconds until the reset), so a client can back off uniformly on any 429 without special-casing which limiter fired.

{
  "data": null,
  "error": "Daily API request limit exceeded",
  "meta": {
    "code": "rate_limit_exceeded",
    "retryAfter": 33421
  }
}

The public GET /api/v2/changelog has neither: it is limited to 60 requests a minute per IP address (bucket publicChangelog) and never counts toward the daily quota.

Handling errors#

const res = await fetch('https://www.trackagoat.com/api/v2/creators', {
  headers: { Authorization: `Bearer ${apiKey}` },
});
 
const body = await res.json();
 
if (!res.ok) {
  if (res.status === 429) {
    const retryAfter = body.meta?.retryAfter ?? 60;
    // wait retryAfter seconds and retry
  } else {
    throw new Error(body.error ?? `HTTP ${res.status}`);
  }
}
 
const creators = body.data;