# Fehlercodes

> https://storelift.net/de/docs/api/errors/

Jeder Fehler aus `/v1` hat denselben Body. `error` ist ein stabiler Code, nach dem Sie verzweigen können; `message` erklärt ihn in einem Satz, und `docs` verlinkt hierher.

Fehlermeldungen stehen auf Englisch, so wie die API sie zurückgibt; darunter folgt die deutsche Fassung.

```json
{
  "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 | Meldung |
| --- | --- | --- |
| `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. |