Error Reference

32 Error Codes

Complete reference for all Sphyr gateway and SDK error codes. Each code links to detailed documentation including cause, retryability, and remediation steps.

6 retryable 26 non-retryable

SESS_INVALID The session token is missing, malformed, or has been invalidated. Non-retryable
SESS_IP_MISMATCH The request IP does not match the IP recorded for this session. Non-retryable
SIG_INVALID The HMAC signature on the request is invalid or was computed with the wrong secret. Non-retryable
SIG_EXPIRED The request timestamp is outside the allowed clock-skew window. Non-retryable
SIG_PROCESSING_ERROR An internal error occurred while verifying the request signature. Non-retryable
RATE_LIMITED The request has been rate-limited. Too many requests in the current window. Retryable
GLOBAL_PAUSE The Sphyr gateway is temporarily paused for maintenance or overload protection. Retryable
SSRF_BLOCKED The target URL points to an internal network address (SSRF protection). Non-retryable
INVALID_URL The target URL is not a valid, parseable URL. Non-retryable
HTTPS_REQUIRED The target URL uses a non-HTTPS scheme. Only HTTPS targets are permitted. Non-retryable
DOMAIN_BANNED The target domain is on the Sphyr blocklist. Non-retryable
DNS_FAILED DNS resolution of the target hostname failed. Non-retryable
HONEYTOKEN The request matched a honeytoken pattern — a known credential canary. Non-retryable
DB_OVERLOAD The Sphyr database is temporarily overloaded. Retryable
FETCH_ERROR The upstream HTTP request to the target URL failed due to a network error. Retryable
REDIRECT_BLOCKED The target URL returned a redirect to a disallowed destination. Non-retryable
INSUFFICIENT_CREDITS Your account has no remaining Sphyr credits. Non-retryable
HEADER_COLLISION The request contains a header that conflicts with a Sphyr-managed header. Non-retryable
HEADER_INVALID A request header has a malformed or invalid value. Non-retryable
AUTH_FAILED API key authentication failed. The key is missing, expired, or revoked. Non-retryable
KEY_PAUSED Your API key has been manually paused in the Sphyr console. Non-retryable
ENTROPY_BLOCKED The request was blocked by the entropy gate — a low-entropy or duplicate nonce was detected. Non-retryable
KEY_BUDGET_EXCEEDED Your API key has exceeded its configured per-period spending budget. Non-retryable
SESSION_CREATE_FAILED The session could not be created due to a transient backend error. Retryable
FAIL_SAFE_EXHAUSTED All fail-safe retry attempts have been exhausted. Retryable
HOURLY_BUDGET_EXCEEDED Your account's hourly spending budget has been exceeded. Non-retryable
INBOUND_SAFETY_BLOCKED The inbound request was blocked by a safety policy check. Non-retryable
CONFIG_MISSING A required configuration value is missing from the SDK or proxy environment. Non-retryable
IDEMPOTENCY_CONFLICT A request with this idempotency key was already processed with different parameters. Non-retryable
GATEWAY_UNREACHABLE The Sphyr gateway was unreachable. The SDK could not establish a connection to route the request. Non-retryable
CONFIG_ERROR A required gateway configuration value is missing or invalid on the Sphyr deployment. This is an infrastructure error, not a client-side error. Non-retryable
MCP_HTTP_ERROR The upstream MCP server returned an unexpected HTTP error response. The Sphyr proxy could not complete the MCP tool call. Non-retryable

← Back to Developer Docs