Response & Error Codes

Understanding how EdgeWrap handles response envelopes and error codes helps you build reliable client integrations.

Edge Proxy Error Responses

When a request is rejected by the EdgeWrap proxy gateway before it reaches your origin, it returns a standard JSON error envelope containing a success status and a description.

Proxy Error Response

{
  "success": false,
  "error": "Request blocked by WAF",
  "requestId": "req_abc123def456"
}

HTTP Status Codes

The Edge Proxy and Gateway return standard HTTP status codes mapping to the outcome of each request:

Status	Meaning	Common Cause
200	OK	Request successfully processed and forwarded (or served from edge cache).
201	Created	Resource successfully created at your origin server.
400	Bad Request	The request body failed gateway input validation, or the request format is invalid.
401	Unauthorized	Missing or invalid x-api-key header on the request.
403	Forbidden	The request was blocked by WAF policies, IP blacklists, bot detection, or a plan threshold has been reached.
404	Not Found	The requested path or resource does not exist at your origin, or the project routing configuration is missing.
429	Too Many Requests	The DDoS protection engine or per-key rate limiters have been triggered for the client IP.
502	Bad Gateway	The gateway failed to connect to your origin server after executing all retry cycles.
503	Service Unavailable	Your origin server is failing and the Circuit Breaker has transitioned to the OPEN state.

Proxy-Specific Gateway Errors

This table details the exact error strings generated by EdgeWrap when short-circuiting a request in the proxy pipeline:

HTTP	Error Message	Pipeline Trigger
401	"Missing API key"	No x-api-key header was provided in the incoming request.
401	"Invalid or revoked API key"	The provided key hash was not found, was deactivated, or expired.
403	"Platform not allowed for this API key"	The key does not support the request's client platform (e.g. mobile key used in web context).
403	"Project is in readonly mode"	The project is paused due to subscription billing issues.
429	"Free quota exhausted. Upgrade to continue."	The monthly free quota tier has been exceeded.
429	"Monthly quota exceeded."	The paid plan's request quota has been hit (and pay-as-you-go is disabled).
429	"PAYG spend cap reached."	A custom daily or monthly pay-as-you-go spend cap has been hit.
429	"Too many requests"	DDoS mitigation or rate limits have been triggered for the client IP.
403	"WAF: Request blocked"	OWASP filters or custom Edge Rules blocked the request pattern.
503	"Origin unavailable"	The circuit breaker is OPEN due to origin failures, and no stale cache is available.
502	"Bad gateway: origin timeout"	Origin servers timed out during health checking or proxy fetch attempts.

Handling Gateway Throttling (429)

Client applications should always monitor for HTTP 429 response statuses. When EdgeWrap rate limits a client, it attaches a Retry-After header indicating how many seconds to wait before attempting another request.

Sample Throttling Response Headers

HTTP/2 429 Too Many Requests
Retry-After: 30
Content-Type: application/json

{
  "success": false,
  "error": "Too many requests",
  "requestId": "req_xyz789abc"
}

Tip: Implement exponential backoff retry policies in client SDKs. Respect the Retry-After duration header for immediate pause windows when throttling occurs.