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 can return a recoverable envelope instead of data when the Search Console connection 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`	No Search Console property is connected.	Connect one in the Dashboard.
`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.

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