API reference

Errors

One error shape on every endpoint, stable codes to branch on, and when to retry.

Error shape#

Every error, on every endpoint, is JSON in one shape, with CORS headers so browser code can read it. That includes unknown paths (404 not_found) and methods an endpoint doesn't take (405 method_not_allowed, with an Allow header).

401 response · HTTP

HTTP/1.1 401 Unauthorized
Request-Id: req_4f8a1c2e9b7d3a6c5e0f1b2d

{
  "error": {
    "code": "invalid_public_key",
    "message": "The publicKey is unknown, belongs to an archived project, or was rotated and its grace period ended.",
    "docs": "https://tughq.com/docs/api/errors#error-invalid_public_key",
    "requestId": "req_4f8a1c2e9b7d3a6c5e0f1b2d"
  }
}

docslinks to the code's entry in the catalogue below.

Handling errors#

  • Branch on code. Codes are stable: never renamed or removed, only added. message is for people and may change.
  • Quote requestId (also the Request-Id header, sent on successes too) when you contact support.
  • Retry only 429, 500 and 503. For 429 and 503, wait Retry-After seconds first. Other 4xxerrors won't succeed unchanged.

Error codes#

  • invalid_request400Fix, then resend

    A field is missing or invalid. The message names the field.

  • invalid_json400Fix, then resend

    The body is empty or isn't valid JSON.

  • missing_public_key400Fix, then resend

    No publicKey was sent. Send it in the body (POST) or the query string (GET).

  • unknown_surface400Fix, then resend

    The surface in the URL isn't one Tug knows. The message lists the valid ones.

  • holdout_feedback400Fix, then resend

    Only shown can be reported for a holdout (control group) entry: those users never saw the message.

  • invalid_public_key401Fix, then resend

    The publicKey is unknown, belongs to an archived project, or was rotated and its grace period ended.

  • invalid_api_key401Fix, then resend

    The Authorization header isn't Bearer tug_…, or the key is unknown or revoked.

  • server_key_required401Fix, then resend

    This endpoint or option needs a server API key (Authorization: Bearer tug_…).

  • missing_user_hash401Fix, then resend

    The project requires identity verification and no userHash was sent. Compute it on your server.

  • invalid_user_hash401Fix, then resend

    userHash doesn't match HMAC-SHA256(identity secret, userId). Check the secret and that you hashed the same userId.

  • trial_expired402Fix, then resend

    The workspace's trial has ended. Choose a plan under Settings, Billing.

  • billing_inactive402Fix, then resend

    The workspace's subscription isn't active. Update billing under Settings, Billing.

  • plan_limit_reached402Fix, then resend

    This month's event or decision allowance for the plan is used up.

  • feature_not_in_plan402Fix, then resend

    The plan doesn't include this feature.

  • origin_not_allowed403Fix, then resend

    The request's Origin isn't the project's Allowed origin.

  • api_key_project_mismatch403Fix, then resend

    The server API key belongs to a different workspace than the publicKey.

  • webhook_not_enabled403Fix, then resend

    PostHog forwarding isn't turned on for this project.

  • not_found404Fix, then resend

    No API endpoint at this path.

  • decision_not_found404Fix, then resend

    No served decision matches this logId (or recommendationId) for this user.

  • project_not_found404Fix, then resend

    The project query parameter isn't a project in the API key's workspace (or it is archived). Copy the id from GET /projects.

  • method_not_allowed405Fix, then resend

    The endpoint exists but not for this HTTP method. The Allow header lists the methods it takes.

  • payload_too_large413Fix, then resend

    The body or the batch is over the documented size limit.

  • rate_limited429Retry after Retry-After

    Too many requests in this window. Wait for Retry-After seconds, then retry.

  • internal_error500Safe to retry

    Something failed on Tug's side. It is safe to retry.

  • service_unavailable503Retry after Retry-After

    Tug's database couldn't be reached. Retry after a short wait.

  • PageOverviewGet started
  • PageQuick startGet started
  • PageConceptsGet started
  • PageScript tag (tug.js)Install
  • PageReactInstall
  • PageNode and serverInstall
  • PageIdentity verificationGuides
  • PageCounting and holdoutsGuides
  • PagePostHogGuides
  • PageEnvironmentsGuides
  • PageData requestsGuides
  • PageOperator consoleGuides