Error codes

Summary#

This is the complete error catalogue for the Metric Vault HTTP API. It covers the machine-readable code values, the HTTP statuses they arrive with, the exact message text, the cause, and the fix. Support engineers can match a customer's screenshot to a row here; developers can build retry logic from the "Retry" column without guessing.

Overview#

The two error shapes#

Most of the API returns a flat object:

{ "error": "Human-readable message" }

Gated failures add a machine-readable code and, where it helps, structured context:

{
  "error": "You've used all 500 premium reports on the PRO plan this month. Light tools (keyword research, SERP, content, technical audits) keep working. Quota resets on September 1, 2026 (in 26 days). Upgrade to continue using premium reports now.",
  "code": "quota_exceeded",
  "plan": "pro",
  "used": 500,
  "quota": 500,
  "cost": 6,
  "reset_at": "2026-09-01T00:00:00.000Z",
  "reset_date": "September 1, 2026",
  "days_until_reset": 26,
  "upgrade_url": "https://metricvaultai.com/index.html#pricing"
}

The blog sub-router uses a nested shape instead:

{ "error": { "code": "forbidden", "message": "Your blog role does not allow this action (postWrite)." } }

Reading a response#

• error is always a string, except on the blog sub-router where it is an object.
• code is present only on gated failures. Its absence is normal.
• Some endpoints report failure with HTTP 200. Those are listed separately below; check ok before you check the status.

HTTP status codes#

Machine-readable error codes#

Authentication and entitlement#

Quotas and rate limits#

Quota responses also carry plan, used, quota, cost, reset_at, reset_date, days_until_reset and upgrade_url. Rate-limit responses carry limit, used and reset_in_minutes. See Rate limits and quotas.

Dependency and configuration failures#

Every one of these means the platform refused rather than guessed. They are transient in the first three cases and operational in the rest.

Input validation#

Not found and conflict#

Errors without a code#

The public API and key management#

Tools#

The AI provider's own failures are rewritten into five friendly messages before they reach you: a region message asking you to run again, a rate-limit message asking you to wait ten seconds, a quota-exhausted message, an authentication message pointing at support, and a generic AI request failed. Please try again.

Real-data tools with nothing to report#

Thirty tools are marked as real-data tools and never fabricate numbers. When the provider has no data they return HTTP 200 with:

{ "data": { "noDataAvailable": true, "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." } }

This is a successful response, not an error. Handle noDataAvailable explicitly.

Billing#

Team#

Monitoring, alerts, schedules, sharing#

Branding#

Translation#

Translation otherwise fails open: if a provider errors, the source string is returned unchanged rather than the request failing.

Responsive analyzer#

The preview proxy is the one part of the API that answers with a styled HTML card instead of JSON, using 400 Invalid address, 403 Not allowed, 504 Timed out, 502 Cannot be previewed and 415 Not a web page.

Article queue#

Administration#

Every /api/admin/* route answers a failed authorisation with HTTP 403 and {"error":"Unauthorized"}, not 401. Beyond that:

Internal and diagnostic routes#

See Internal endpoints and Diagnostic endpoints.

Failures that arrive with HTTP 200#

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

/api/library/saved/check also always returns 200, with {"found":false} when nothing matches. That is not an error.

Fail-open and fail-closed behavior#

Knowing which way a gate falls tells you whether a 503 is safe to retry.

Retry guidance#