Error codes

Every error from /v1 has the same body. error is a stable code you can branch on; message explains it in a sentence and docs links here.

{
  "error": "scope_required",
  "scope": "revenue:read",
  "message": "The key does not carry the scope this endpoint needs.",
  "docs": "https://storelift.net/docs/api/errors#scope_required"
}

Code	Status	Message
`missing_api_key`	401	Send the key in the Authorization: Bearer header or x-api-key.
`invalid_api_key`	401	The key is not valid.
`invalid_token`	401	The access token is not valid or has expired.
`account_deleted`	401	The account behind this key was deleted.
`key_expired`	401	The key has expired. Create a new one in Settings › API.
`key_revoked`	401	The key was revoked.
`key_budget_reached`	402	This key has used its monthly credit budget. Raise or remove the budget in Settings › API; other keys are not affected.
`key_limit`	403	This workspace has more live keys than it is entitled to, so this key is on hold. Delete a key in Settings › API or upgrade the plan.
`key_leaked`	401	The key was revoked after it was found in a public repository. Create a new one in Settings › API.
`ip_not_allowed`	403	This key is restricted to other IP addresses (Settings › API › IP allow list).
`key_paused`	403	The key is paused. Resume it in Settings › API.
`plan_required`	403	The API is on the Pro plan and above; MCP is on every plan.
`scope_required`	403	The key does not carry the scope this endpoint needs.
`app_not_allowed`	403	The key is restricted to other apps.
`credits_exhausted`	402	This month's API credits are used up.
`rate_limited`	429	Too many requests for this key. Slow down and retry.
`daily_hive_limit`	429	Today's Hive request allowance is used up. It resets at 00:00 UTC.
`bad_country`	400	Send a two-letter storefront code, e.g. country=us.
`unsupported_platform`	400	This metric source supports iOS. Send platform=ios.
`bad_days`	400	Send a whole number of days between 1 and 90.
`hive_read_failed`	400	Hive could not read this observation. Retry shortly.
`hive_write_failed`	400	Hive could not save this observation. Retry shortly.
`bad_kind`	400	kind must be one of grossing, free, paid, ipad.
`bad_genre`	400	Send genre as an App Store genre id (e.g. 6014) or a category key such as games.
`bad_day`	400	Send day as YYYY-MM-DD, no later than yesterday.
`bad_goal`	400	Send goal as downloads, rank or revenue.
`bad_range`	400	Send from and to as YYYY-MM-DD, from on or before to.
`bad_term`	400	Send a keyword of 1–150 characters.
`bad_app_id`	400	Send an App Store id (digits) or a Play package name.
`not_measured`	404	No verified observation is available for the requested app, keyword or scope. Missing data is not zero. Check the request parameters and follow the linked documentation for available actions.
`not_connected`	404	This source is not connected to the workspace. Connect it under Settings › Connections.
`bad_query`	400	Send q with 1–120 characters.
`bad_id`	400	Send an id from a /v1/search result.
`no_filters`	400	Send at least one filter; the accepted filters are listed in filters.
`bad_filter`	400	A filter value is malformed; the field is named in the response. Ranges take numbers, min on or below max.
`bad_cursor`	400	The cursor is malformed or expired. Pass meta.pagination.nextCursor from the previous response unchanged.
`bad_ids`	400	Send ids as a comma-separated list, between min and max apps.
`explorer_required`	403	This endpoint is not open on this account. Hive endpoints run on purchased API credits or Hive Explorer; keyword gap, keyword research and keyword metrics are Hive Explorer only. See https://storelift.net/hive/api
`method_not_allowed`	405	Reads are GET; POST is taken on /v1/actions, /v1/actions/confirm, /v1/apps/{id}/validate-listing and /v1/hive/keywords/{term}/metrics/measure.
`bad_metrics`	400	metrics is a list of popularity and/or difficulty, each at most once.
`bad_wait`	400	wait is a whole number of seconds from 0 to 20.
`hive_measurement_unavailable`	503	Hive measurement is not available right now. Nothing was used; retry shortly.
`hive_measurement_queue_failed`	503	The measurement could not be queued. Nothing was charged; retry shortly.
`hive_measurement_failed`	503	The source attempt failed. Valid metrics stay in the response; retry later.
`hive_measurement_incomplete`	503	The job finished without a result for every requested metric. Valid metrics stay in the response.
`hive_measurement_deferred`	503	The source deferred this job. Valid metrics stay in the response; retry later.
`hive_measurement_not_started`	503	No measurement job is running for this keyword. Retry the request.
`unknown_action`	400	No such action. Call POST /v1/actions with one of the listed actions.
`invalid_arguments`	400	An argument is missing or malformed; the field is named in the response.
`confirm_token_invalid`	400	The confirmation token is unknown or was already used. Preview the action again.
`confirm_token_expired`	400	The confirmation token expired. Preview the action again.
`confirm_token_mismatch`	409	The target changed after the preview. Preview the action again and re-read the diff.
`write_limit_reached`	403	This write is outside the guardrails for the action (see reason).
`key_in_url`	400	API keys are not accepted in the URL, where logs and proxies keep them. Send the key in the x-api-key header (or Authorization: Bearer) and rotate this one.
`test_key_read_only`	403	Test keys (sl_test_) never write.
`job_not_found`	404	No such job in this workspace.
`workspace_suspended`	403	This workspace is suspended. Contact support@storelift.net.
`ip_list_required`	403	This workspace requires every key to carry an IP allow list. Add one in Settings › API.
`already_measuring`	409	A measurement for this app is already running.
`ai_limit`	429	This month's AI visibility runs are used. The response carries limit and resetsAt.
`in_progress`	409	A write for this target is already running. Wait for it to finish.
`asc_required`	403	Connect App Store Connect under Settings › Connections first.
`asc_role`	403	The App Store Connect key needs the Admin or App Manager role to edit metadata.
`asc_rejected`	502	App Store Connect refused the change; its own message is in detail.
`asc_unavailable`	502	App Store Connect could not be reached. Retry in a moment.
`ios_only`	403	This action needs the App Store side of the app.
`no_editable_version`	404	No editable App Store version. Metadata can only change while a version is in Prepare for Submission or rejected — the current states are listed.
`locale_not_found`	404	That storefront language is not on the version; the available locales are listed.
`changed_since_preview`	409	The listing changed in App Store Connect after the preview. Nothing was written — preview again.
`ai_text_limit`	429	This month's AI writing allowance is used up. resetsAt says when it renews; Settings › Plan adds more.
`ai_not_configured`	503	The AI writer is starting up. Retry in a moment.
`ai_failed`	502	The AI writer returned an answer we could not read. Retry in a moment.
`audit_failed`	502	The storefront scan stopped midway. Start it again with refresh.
`review_ai_limit`	429	This month's Review AI allowance is used up. resetsAt says when it renews; Settings › Plan adds more.
`review_not_found`	404	No review with that id in the stored reviews for this storefront. Take the id from get_reviews or search_reviews.
`bad_locale`	400	The locale is two letters, an underscore and two letters, e.g. de_de, pt_br.
`no_audit`	409	Localization writes from the storefront audit's source listing. Run get_storefront_audit with start for this app, then call again.
`no_storefront`	409	No storefront of this app reads that locale. Pick a locale the storefront audit lists.
`measure_busy`	503	Apple's search is answering slowly this minute; call again shortly. Nothing was used.
`localize_quota`	429	This plan's listing writes for the period are used. The response carries limit, used and period.
`no_job`	404	No localization is running for that locale. Call without poll to start one.
`ai_timeout`	504	The AI writer took too long. Retry in a moment; the allowance was returned.
`not_found`	404	No such app in this workspace.
`unknown_endpoint`	404	No such endpoint.