Errors

This page is for developers calling the API directly. If you use OpenRush through an AI agent, your agent will usually explain these issues in normal language. OpenRush uses standard HTTP statuses for request, auth, credit, provider, and validation failures.

Common HTTP statuses

Status	Meaning	Typical cause
`400`	Bad request	Malformed dataset URI or bad input
`401`	Unauthorized	Missing, invalid, expired, or inactive key
`402`	Payment required	Insufficient credits or gated feature
`404`	Not found	Missing account, credential, or dataset
`422`	Validation error	Request body or query parameter failed schema validation
`429`	Too many requests	Rate-limit window exhausted
`503`	Service unavailable	Provider unavailable or dependency missing

Validation errors

FastAPI validation errors use the standard detail array:

{
  "detail": [
    {
      "type": "greater_than_equal",
      "loc": ["body", "limit"],
      "msg": "Input should be greater than or equal to 1",
      "input": 0
    }
  ]
}

Recoverable dataset states

/v1/tools/export_dataset can return 200 with data.available=false when a valid openrush:// dataset URI has expired. Treat that as a recoverable state. Follow the next_actions entry to regenerate the dataset.

Owned data connection states

get_search_performance, get_website_analytics, and get_ad_performance can return a recoverable envelope instead of data when the connection they need is not ready. These are not failures to retry blindly; each carries a next_action telling you how to recover. No credits are charged in these states.

Code	Meaning	How to recover
`connection_required`	Nothing is connected for this source (no Search Console or Analytics property, or no activated Google Ads account).	Connect one in the Dashboard. For Google Ads, also activate an ad account.
`binding_required`	Connected, but not linked to this website.	Link a property to the website in the Dashboard.
`website_required`	Several connected websites match.	Retry with a `website_id` from `data.options`.
`reconnect_required`	Google access expired or was revoked.	Reconnect in the Dashboard, then retry.
`platform_required`	Several ad platforms are connected.	Retry with a `platform` from `data.options`.
`account_required`	Several Google Ads accounts are activated.	Retry with an `ad_account` from `data.options`.
`account_not_found`	The `ad_account` you passed is not activated on this account.	Retry without `ad_account` to see the activated accounts.

Google Ads can also reject a report it cannot build, for example an unsupported filter and report combination. That comes back as a core.error with code upstream_rejected and retryable: false, with a next_action that retries the same report without filters. Unlike the connection states above, the call has already been charged.

Get started

Guides

Dashboard basics

Developer reference

Common HTTP statuses

Validation errors

Recoverable dataset states

Owned data connection states

​Common HTTP statuses

​Validation errors

​Recoverable dataset states

​Owned data connection states

Common HTTP statuses

Validation errors

Recoverable dataset states

Owned data connection states