Error reference
Every error uses a closed code list, a human-readable fix, and a docs_url pointing at this page. The codes below are the same enum the API returns, including the non-affiliation notice on every error body.
INVALID_INPUT
The body or query does not match the tool schema. Compare it with /openapi.json.
PROGRAM_OUT_OF_SCOPE
That program is stored as out of scope. Send include_out_of_scope true, or request an in-scope program.
MISSING_REQUIRED_FIELD
A required field is missing. The OpenAPI schema lists required fields.
UNKNOWN_FIELD
The request includes a field the schema does not allow.
VALUE_OUT_OF_RANGE
A number is outside the schema minimum or maximum.
VALUE_INCONSISTENT
Caller-supplied metrics cannot be true together. Spotlight hours above total view hours name spotlight_view_time_hours_28d and view_time_hours_28d in fields. View hours that are high for the follower count, including followers of 0, stay warnings because view time can come from non-followers.
UNKNOWN_PROGRAM
The program slug is not in the rules database.
UNKNOWN_METRIC
The metric name is not one the calculators accept.
UNKNOWN_RULE_ID
The rule_id is not in the published rules.
INVALID_DATE
A date is not a valid calendar date in YYYY-MM-DD form.
DATE_RANGE_INVALID
until is earlier than since.
PAYLOAD_TOO_LARGE
The body is over 16 KB.
RATE_LIMITED
The rate limit was exceeded. Wait for the Retry-After interval. The tools are free and rate-limited. A free API key from POST /v1/keys raises the limit.
INVALID_API_KEY
The API key does not match a stored hash. Anonymous access is available if you remove the key.
TURNSTILE_FAILED
The Turnstile check is missing or was not accepted. Complete the check on /keys, or send turnstile_token.
NO_RULES_AVAILABLE
No approved rules are loaded.
UNSUPPORTED_API_VERSION
Only /v1 is supported.
NOT_FOUND
The path or tool name does not exist.
METHOD_NOT_ALLOWED
Use the method named in the Allow header. Calculation tools accept POST only.
INTERNAL_ERROR
The server failed unexpectedly. Retry once.
SERVICE_UNAVAILABLE
The rate limiter or rules bundle is unavailable. Retry shortly.
CONFLICT
That request conflicts with data already stored. Retry with a different value, or email us if it keeps happening.
PAYMENT_REQUIRED
The tools are free. This code is no longer returned for a missing purchase.
WATCH_PLAN_REQUIRED
Eligibility Watch stores numbers on a free API key. Issue one at /keys.
WATCH_PROFILE_LIMIT
This plan has no room for another Watch profile.
WATCH_PROFILE_READ_ONLY
This profile is read-only after a move to Personal. You can still export or delete it.
WATCH_NOT_FOUND
That Watch profile was not found.
WATCH_DATE_OUT_OF_RANGE
That date is outside the range Watch can save.
WATCH_EMPTY_INPUT
A save needs at least one metric.
WATCH_EMPTY_CHECKIN
That save would leave the check-in with no numbers.
WATCH_SAVE_LIMIT
This key has used today's save limit.
WATCH_LABEL_REJECTED
That nickname is not allowed.
WATCH_WEBHOOK_URL_REJECTED
That webhook address is not allowed.
KEY_ROTATION_CONFLICT
This key was already replaced.
REPLACEMENT_LINK_INVALID
That replacement link is used up or expired.