SYSTEM ACTIVE
m mcpmeter
Sign up
Sign up Sign in
HOME / DOCS / STATUS CODES & ERRORS
DOCS NAV · STATUS CODES & ERRORS ▾
GET STARTED
Quickstart Concepts
INTEGRATIONS
Clients & code samples
META
Changelog
DOC CORE

STATUS CODES & ERRORS

Every status the proxy can return, what it means, and the recovery step.

v0.1.0 UPDATED 2026-05-09 ~5 MIN READ

PHILOSOPHY

The proxy is honest about why a call failed. We use HTTP status codes for proxy-level decisions (auth, billing, rate limits, upstream availability) and pass through everything else from the publisher's MCP unchanged.

If you only handle two failure modes — handle 402 (top up) and 429 (back off).

REFERENCE

Every code you can see, grouped by class. Click any card to jump to its example body.

2XX · SUCCESS

200 PROXY · OK
Forwarded successfully.
Whatever the upstream tool said. Debit applied.
SOURCE · PROXY
2xx UPSTREAM
Other 2xx codes pass through from the publisher.
Treat as success.
SOURCE · PUBLISHER

4XX · CLIENT

400 MALFORMED
Your MCP client sent something we can't parse.
Email support with the request ID.
SOURCE · PROXY
401 AUTH FAIL
Missing, unknown, or revoked bearer key.
Mint a new key.
SOURCE · PROXY
402 NO CREDIT
Insufficient balance and no free-tier remaining.
Top up.
SOURCE · PROXY
402 CAP REACHED
Project's monthly spending cap exceeded.
Raise the cap or wait for the 1st.
SOURCE · PROXY
403 SUSPENDED
Account suspended by platform.
Email support.
SOURCE · PROXY
404 NO SLUG
No MCP listing matches that slug.
Browse the marketplace.
SOURCE · PROXY
410 ARCHIVED
Listing was archived; no longer live.
Pick another from the marketplace.
SOURCE · PROXY
429 RATE LIMIT
Per-minute or per-day cap exceeded for this listing.
Honour Retry-After. See rate limits.
SOURCE · PROXY
4xx UPSTREAM
Other 4xx pass through from the publisher's MCP.
Read the upstream error message.
SOURCE · PUBLISHER

5XX · SERVER

502 UPSTREAM ERR
Upstream returned 5xx or errored mid-stream.
Debit auto-refunded. Retry; pick another listing if persistent.
SOURCE · PROXY
503 PAUSED
Publisher paused the listing.
Pick another listing.
SOURCE · PROXY
504 TIMEOUT
Upstream didn't respond within 30s.
Debit auto-refunded. Retry.
SOURCE · PROXY

ERROR BODY

Proxy errors return a JSON body alongside the HTTP status — matching JSON-RPC 2.0 error shape so MCP clients can surface it cleanly:

402 response bodyJSON-RPC 2.0
{
  "jsonrpc": "2.0",
  "id": "req_82",
  "error": {
    "code":    -32402,
    "message": "Insufficient credit",
    "data": {
      "reason":        "out_of_credit",
      "balance_micro": 240,
      "price_micro":   800,
      "topup_url":     "https://mcpmeter.com/billing/topup"
    }
  }
}

The data object's shape varies by error. Common fields:

  • reason — machine-readable code (out_of_credit, cap_reached, rate_limited, upstream_error, …).
  • request_id — mirrors the X-Mcpmeter-Request-Id header.
  • retry_after — seconds, on 429.
  • balance_micro, price_micro — on 402.

AUTOMATIC REFUNDS

GOOD NEWS

If the upstream returns 5xx or times out, the debit is automatically reversed by the proxy in the same request. You will not be charged for failed publisher calls.

You'll see two ledger rows in your activity log: a usage debit and a refund credit, both for the same µ¢ amount. The publisher does not earn payout for failed upstream calls.

REPORTING AN ISSUE

FAST TRIAGE

Quote X-Mcpmeter-Request-Id when emailing [email protected]. We can pull the entire call's metadata from that ID alone — no need to attach logs.