Error and status codes

Summary#

Two lookups in one page. The first is alphabetical by code, for anyone reading a response body or a log line. The second runs the other way, from the message a customer can see on their screen back to the code behind it, for anyone on a support call holding a screenshot. Both are complete for the codes the platform emits.

Overview#

A failed request returns a human message and, when the failure came from a gate rather than from a handler's own validation, a stable machine code.

{
  "error": "This tool needs a paid plan. Free includes the 10 technical SEO tools; upgrade to Pro to unlock the rest.",
  "code": "upgrade_required",
  "current_plan": "free",
  "required_plan": "pro",
  "upgrade_url": "https://metricvaultai.com/pricing"
}

Three rules for reading one:

• Branch on code, never on the message. Messages are translated in the interface and their wording changes; codes are stable.
• code is often absent. Plain validation failures return error only. That is normal, not a malformed response.
• A 200 is not always a success. A few endpoints report failure inside the body. They are listed near the end of this page.

Quota and plan failures carry extra structured fields. Quota responses add plan, used, quota, cost, reset_at, reset_date, days_until_reset and upgrade_url. Rate-limit responses add limit, used and reset_in_minutes. Plan gates add current_plan, required_plan and upgrade_url.

HTTP statuses#

Every administration route answers a failed authorisation with 403 and {"error":"Unauthorized"}, not 401.

Codes, A to Z#

From the message on screen back to the code#

The messages a customer is most likely to read out or screenshot, and what they mean. Quoted exactly.

Error message reference carries the wider set of interface messages, including the ones that never reach an API response.

Failures without a code#

Plain validation failures return error only. They are grouped by feature in Error codes, which is the endpoint-by-endpoint catalogue. The families are:

Failures reported with HTTP 200#

Three places report a failure inside a successful response. Check the body, not the status.

Checking for an existing saved result also always returns 200, with {"found":false} when nothing matches. That is not an error.

Thirty tools are marked as real-data tools and never invent numbers. When the provider has nothing they return 200 with noDataAvailable: true and the message No measured data was found for "<query>". This is a real-data tool, so Metric Vault shows nothing here rather than fabricating a number. Check the spelling, or try a more established domain, keyword or topic. That is a successful run with an honest empty result. See A tool returned no data.

Fail-open and fail-closed#

Knowing which way a gate falls tells you whether a 503 cost anything.

Retry guidance#