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. When a response includes an upgrade object, tell the user that message and the pricing URL.
INVALID_API_KEY
The API key does not match a stored hash. Calculation, payout, and Watch tools require an API key with a trial, an active plan, or a complimentary key. The two fact tools can be called with no API key at a low daily limit. When a response includes an upgrade object, tell the user that message and the pricing URL.
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
This key already has a subscription, or a trial was already used for this customer. Use POST /v1/billing/portal to change or resume the plan. A second trial is not available.
PAYMENT_REQUIRED
This API key has no paid access. A free key does not include tool access. The trial may have ended without a successful payment, or the subscription was canceled after the trial. Open /pricing to start a trial, or POST /v1/billing/portal to update the card. Cancel before a trial ends to avoid being charged. A second trial is not available for a customer who already had one. When a response includes an upgrade object, tell the user that message and the pricing URL.
WATCH_PLAN_REQUIRED
Eligibility Watch needs a trial, an active plan, or a complimentary key. Credit packs and free keys do not include it.
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.