Errors

What an error response looks like, what each status code means, and the list of every error code.

What an error looks like

Every error has a body in the same format, whatever went wrong:

{
  "error": {
    "code": "filter_value_invalid",
    "message": "Unknown engine \"chatgpt4\". Valid values: chatgpt, gemini, perplexity, ai_mode, copilot, google_ai_overview, claude.",
    "param": "engine"
  }
}

Field	Meaning
`code`	A fixed code for your program to check. Check the HTTP status first, then this code.
`message`	A sentence for a person to read. The wording can change, so your program should not read it.
`param`	The query parameter or body field that caused the error, or `null` when the error is not about 1 field.

Status codes

Status	Meaning
`400`	A parameter or body field is not valid, or a change would go over a limit of your plan.
`401`	The request has no key, or the key has the wrong format, is unknown, or was revoked.
`403`	A read key called a write endpoint, the plan does not include API access, or the request used plain HTTP.
`404`	The item does not exist, or it belongs to another brand. Both cases return the same body.
`409`	The brand already has a prompt with this text.
`429`	The brand went over the rate limit, or is running too many reports at once.
`500`, `503`	An error on our side. You can send the request again.

After a 429, wait the number of seconds in the Retry-After header, then send the request again. After a 500 or a 503, wait and retry, and wait twice as long after each failure. Do not send a request that got 400, 401, 403, 404, or 409 again without changing it: it gets the same error. See Rate limits.

Every error code

Code	Status	Meaning
`parameter_invalid`	`400`	A parameter or body field has a wrong value or format. `param` names it.
`parameter_missing`	`400`	A required parameter is missing.
`body_invalid`	`400`	The body is not JSON, or `Content-Type: application/json` is missing.
`filter_value_invalid`	`400`	A filter has an unknown value: an engine, a country, or an id that is not in your brand. The message names the value. You also get this code for the `prompt_id` of an archived prompt without `include_archived=true`.
`filter_field_invalid`	`400`	The report does not accept this filter, for example `domain` on the visibility report.
`date_range_invalid`	`400`	`end_date` is before `start_date`, or the range is longer than 90 days.
`dimension_invalid`	`400`	A dimension is unknown or repeated, the request has 2 time dimensions or more than 3 dimensions, or it has both `domain` and `url`.
`order_field_invalid`	`400`	`order_by` names a column the report does not return, or a direction other than `asc` or `desc`.
`effective_prompt_quota_exceeded`	`400`	The change would track more prompts than the plan allows. 1 prompt in 1 country counts as 1.
`onboarding_prompt_cap_reached`	`400`	The brand is still being set up, and the change would go over the limit for setup.
`unsupported_region`	`400`	A country Lumirank does not track.
`cannot_modify_self`	`400`	The id is your own brand. Its competitor status cannot change.
`api_key_missing`	`401`	The request has no `Authorization` header.
`api_key_invalid`	`401`	The key has the wrong format, is unknown, or was revoked.
`insufficient_permission`	`403`	A read key called a write endpoint.
`plan_upgrade_required`	`403`	The organization's plan does not include API access.
`https_required`	`403`	The request used plain HTTP. Use `https://`.
`resource_missing`	`404`	Your brand has no item with this id.
`prompt_already_exists`	`409`	The brand already has a prompt with this text, in any status. The message gives that prompt's id and status.
`rate_limited`	`429`	The brand made more than 200 requests this minute.
`too_many_concurrent_reports`	`429`	The brand already has 4 reports running.
`internal_error`	`500`	Something failed on our side.
`report_timeout`	`503`	The report took too long. Send it again, or ask for a shorter date range or fewer dimensions.

New error codes can be added to v1. If you get a code you do not know, handle it by its HTTP status.

What an error looks likeCopy Anchor Link

Status codesCopy Anchor Link

Every error codeCopy Anchor Link

On this page

What an error looks like

Status codes

Every error code