Appearance
Deny codes
When the regional gateway rejects a tenant request before relaying to your backend, you typically receive HTTP 502 with:
Content-Type: application/vnd.xg3.error+json- JSON body:
{ "code": "...", "message": "..." } X-Xg3-Request-Id— use with console Request Lookup
OAuth token errors (POST /oauth/token) use 401/403 with standard OAuth error JSON instead — not covered in detail here.
RateLimited is HTTP 429 (not 502) and includes Retry-After — Service ingress rate limits.
How to read the error
json
{
"code": "TokenInvalid",
"message": "Secret is corrupt"
}| Field | Meaning |
|---|---|
code | Machine-readable deny reason (PascalCase string) |
message | Human-readable explanation |
X-Xg3-Request-Id | Correlation id on response headers |
Deny code reference
| Code | Typical cause | What to do |
|---|---|---|
| RegionMismatch | Service region does not match hostname region | Use correct regional hostname |
| ServiceNotFound | Unknown service id or deleted service | Check service id in URL; create or restore service |
| ServiceDisabled | Service or account disabled | Enable in console |
| TokenMissing | Required auth header missing or empty | Send X-Xg3-Authorization or X-Xg3-Service-Key per service auth mode |
| TokenInvalid | Bad JWT, wrong secret, or invalid service key | Re-mint token; verify credential or key |
| TokenExpired | JWT past expiry | Get a new token from /oauth/token |
| TokenRevoked | Credential revoked | Rotate credential and mint new token |
| PolicyDenied | Both auth headers sent on same request | Use only one of JWT or service key |
| AgentUnavailable | Agent disabled or not connected at authorize time | Check agent enabled and tunnel status |
| RateLimited | Too many requests | Honor Retry-After; see Service ingress rate limits |
| CredentialDisabled | OAuth credential disabled or missing | Enable or recreate credential |
| AudienceMismatch | Token or credential not valid for this service hostname | Fix scope at mint; update credential allowlist |
| KeyNotAllowedForService | Credential or key not allowed for this service | Add service to allowlist |
| RenewalLimitExceeded | Agent certificate renewal limit | Do not restart agent in a loop — contact support |
| AgentDisabled | Agent disabled | Enable agent in console |
| AuthModeNotSupported | Wrong auth mechanism for service (e.g. key on JWT-only service) | Match client to service auth modes |
| AccountNotFound | Account in token scope does not exist | Verify account id |
| AccountDisabled | Account disabled | Contact account admin |
| InvalidScope | OAuth scope format wrong | Use account:ACCOUNT_ID service:SERVICE_ID |
| ScopeAccountMismatch | Scope account does not match credential | Align scope with credential account |
| InternalBackendAccessDenied | Backend URL is private/internal and agent not permitted | See below |
| TrialExpired | Account trial ended without subscription | Subscribe on Billing |
Gateway-only statuses (not in table above) include ControlPlaneUnavailable, AGENT_UNAVAILABLE (504), TUNNEL_OVERLOADED — see Troubleshooting.
Backend TLS errors
When the agent cannot complete a TLS handshake to your HTTPS backend under the service’s TLS Policy, the client receives HTTP 502 with:
Content-Type: application/vnd.xg3.error+json- Header
X-Xg3-Status: XG3_BACKEND_TLS_ERROR(also present aserror.code) - Nested envelope:
json
{
"error": {
"code": "XG3_BACKEND_TLS_ERROR",
"message": "Backend TLS failed: the certificate was not signed by a trusted CA.",
"request_id": "...",
"details": {
"policy": "strict",
"reason": "unknown_ca",
"sha256_spki": "...",
"sha256_cert_der": "..."
}
}
}details.reason | Typical meaning |
|---|---|
unknown_ca | Certificate not issued by a trusted CA (strict mode) |
hostname_mismatch | Certificate does not match the backend hostname |
expired / not_yet_valid | Certificate validity window |
pin_mismatch | Leaf does not match a configured pin |
malformed_policy | Pinning configured without usable pins |
Use sha256_spki or sha256_cert_der from details (or Request Lookup) as the pin algorithm and digest when configuring Pinning on the service — the console algorithm values use the same names. See TLS Policy.
TrialExpired
Your account’s 14-day free trial has ended and there is no active subscription.
Symptoms:
- Ingress requests return 502 with
code: "TrialExpired" - You cannot enable agents or Services in the console
Fix: An account admin opens Billing, chooses a plan, and completes Subscribe (Stripe Checkout). After payment, status becomes Active and access is restored.
See Billing and subscriptions for the full lifecycle.
InternalBackendAccessDenied
Your service backend base URL points to a private or internal network address (for example http://localhost, https://192.168.1.10, or https://app.internal.local), and the agent is not permitted to reach internal targets.
Fix (choose one):
- In the console, open the agent for this service → Edit settings → enable Allow internal backend targets; or
- Change the service backend URL to a publicly routable address reachable from your agent host.
Important: Disabling Allow internal backend targets immediately stops traffic to affected services — you do not need to edit each service separately.
Internal addresses include common private IP ranges, loopback, link-local addresses, and hostnames like localhost and *.local. Hostnames that only resolve to private IPs through DNS may not be detected unless they match these rules.
When creating or editing a service, the console may block an internal URL before submit if the agent setting is off.