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.messageis for people and may change. - Quote
requestId(also theRequest-Idheader, sent on successes too) when you contact support. - Retry only
429,500and503. For429and503, waitRetry-Afterseconds first. Other4xxerrors 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
showncan 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
projectquery 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.