---

title: Error Codes description: The HTTP status codes and error.code values GuardProxy returns, and how to handle each one. group: Reference order: 1

Error Codes

GuardProxy generates a small number of responses itself. Everything else is forwarded verbatim from the upstream. This page lists the responses you may see from the proxy and what each one means.

Status codes from the proxy

Status	error.code	Meaning
403	method_blocked	The request's method is blocked on this upstream (and the path isn't allowlisted).
403	ip_blocked	The request's source IP is not on this upstream's IP allowlist (Pro).
429	rate_limited	The monthly request limit for your plan (20K Free / 50K Pro / 250K Team) has been reached.
429	upstream_rate_limited	The per-upstream rate limit for this upstream has been exceeded (Pro).
413	response_too_large	The upstream response exceeded the size limit.
413	request_too_large	The request body exceeded the 10 MB size limit.
502	upstream_unreachable	The upstream didn't respond or returned a network error.
404	not_found	The customer or upstream slug wasn't found.

403 — method_blocked

The safety net working as intended. The request's HTTP method is on the upstream's blocked list and the path isn't on the allowlist.

{
  "error": {
    "code": "method_blocked",
    "message": "POST is blocked on this upstream"
  }
}

Don't retry. Don't escalate it as an upstream error. If the call genuinely needs to write, surface that to the user — GuardProxy blocked it by design.

403 — ip_blocked

The request came from a source IP that isn't on this upstream's IP allowlist. Add the calling IP to the allowlist, or remove the allowlist to allow all IPs. Like method_blocked, don't retry — the block is by design.

429 — rate_limited

Returned when the account has reached its monthly request limit for its plan (20,000 on Free, 50,000 on Pro, 250,000 on Team per calendar month — both allowed and blocked requests count). Requests resume automatically when the counter resets at the start of the next cycle, or you can upgrade your plan for a higher limit. This is not the upstream's rate limit — that's forwarded as its own 429 with the upstream's Retry-After header.

429 — upstream_rate_limited

The per-upstream rate limit for this upstream has been exceeded. A Retry-After: 60 header is returned. Wait for the minute window to roll over and retry; or raise/remove the per-upstream limit. This is separate from the monthly plan limit above.

413 — response_too_large

The upstream response exceeded the 100 MB size cap. The connection is closed. If you need to transfer payloads this large, paginate at the upstream instead.

413 — request_too_large

The request body exceeded the 10 MB inbound cap and was rejected before reaching the upstream. Reduce the payload size or paginate at the source.

502 — upstream_unreachable

The upstream URL didn't resolve, refused the connection, or timed out. Verify the upstreamUrl configured for the upstream is correct and reachable. This is also returned if the upstream URL fails SSRF validation at request time.

404 — not_found

The customer slug (subdomain) or upstream slug (first path segment) doesn't match a configured record. Confirm the slugs against GET /api/upstreams → proxy_endpoint. The same generic response is returned whether the customer or the upstream is unknown.

Forwarded upstream responses

Every other status code you see — 200, 201, 400, 404 from the upstream, 429 from the upstream, 500, etc. — comes straight from the upstream API, unchanged. GuardProxy forwards status, headers, and body verbatim. Treat them exactly as you would calling the upstream directly.