Troubleshoot API Gateway

Resolve common Admin Console and Developer Portal authentication, configuration, deployment, and access problems.

This guide covers common failure modes in both the Admin Console and the Developer Portal, grounded in how the backend actually reports errors. Both apps show errors the same way: a red status banner with a role=“alert” message, immediately below the form or panel where the action was triggered — the banner text is almost always the backend’s raw error message.

General principles

Errors are surfaced verbatim. Both UIs render err.message from the failed API call directly into the error banner, so the wording you see in the console/portal is close to the literal backend error string.
No client-side rollback. In the Admin Console’s Quick Publish/Wizard flows, each step (environment → upstream → API → version → route → policies → activation) runs sequentially and reports ✓ as it succeeds. If a later step fails, the earlier steps are not undone — you’ll have a partially-created set of resources. Use the APIs tab’s Browse APIs panel to see exactly what exists, and either finish the remaining steps manually (Policies tab, etc.) or clean up.
A generic 500 doesn’t always mean “server broken.” Two specific admin console actions — activating a configuration version and publishing a route — return a 500-level error even when the underlying cause is a user-fixable validation problem (e.g. an invalid configuration snapshot). If you get an unexpected server error immediately after changing a route/policy, re-check your configuration for validity (try Preflight on the APIs tab first) before assuming an infrastructure problem.

Admin Console

“Admin Token is required” / actions are grayed out

You haven’t entered a token yet, or you cleared it with Sign Out. Paste a token or use Sign in with SSO. See Getting Started.

“authorization token is required” / “authorization token is invalid” (401)

The token is missing, malformed, or failed signature/issuer/audience/expiration verification. Get a fresh token (locally: re-run the dev token generator — tokens expire after 1 hour) or sign in again via SSO.

“required role is missing” (403)

Your token is valid but doesn’t carry the role the action needs. Common cause: trying to create an environment, touch SSO Admin Authentication, or approve canary auto-promotion with an environment-scoped role instead of the global admin role. See Permissions.

“publishing to this environment requires an approved change record; use a global admin to bypass”

The target environment has “requires approval” turned on, and you’re signed in as an environment-scoped admin, not a global admin. Either have a global admin perform the publish/activate/rollback/reconcile, or use the Production Approvals tab first if what’s actually blocked is an API version’s lifecycle transition (a different, related gate — see the Admin Console Guide).

Environment/API/route/application/certificate creation fails with a database constraint-style message

These resources have uniqueness rules enforced at the database level, so a duplicate attempt surfaces as a raw constraint-violation error rather than a friendly “already exists” message:

Environment key must be globally unique.
API slug must be unique within its environment.
API Version version string must be unique within its API.
Route path must be unique within its API version.
Application name must be unique within its environment.
Certificate SNI must be unique among active certificates in an environment (you can have a rotated-out inactive one with the same SNI).
API Product slug (per environment) and API Product Plan slug (per product) must be unique.

Fix: change the conflicting field (usually the key/slug/path/name) and retry.

Certificate upload fails with an SNI mismatch

The backend requires the SNI you specify to match either a DNS Subject Alternative Name in the certificate or its Subject Common Name (case-insensitive). If you see an error like “sni does not match certificate subject or SAN,” double-check you typed the exact hostname the certificate was actually issued for. Other certificate failures to expect: an already-expired certificate is rejected outright, and a private key that doesn’t cryptographically match the certificate’s public key is also rejected.

Canary deployment creation fails: “canary traffic percentage must be between 1 and 100”

Traffic % must be an integer 1–100 (0 or negative disables/invalid). Also note: only one active canary deployment is allowed per API version — if you already have one running for that version, delete or complete it first (“active canary deployment already exists for version…”).

Canary auto-promotion doesn’t seem to happen

This is by design, not a bug: auto-promotion is fail-closed. If the last 5 minutes of runtime metrics (p95 latency, error rate) are missing or incomplete for the environment, the canary is simply skipped, not promoted — and no error is shown, because from the system’s perspective nothing went wrong, it just isn’t confident enough to act. Check the Operations tab’s Platform Overview to confirm metrics are actually flowing for that environment before expecting auto-promotion to fire.

Blue-green promote/rollback fails: “cannot promote/rollback blue-green deployment in status…”

Promotion is only valid from active status; rollback is only valid from active or promoted. If a deployment is already promoted, you cannot promote it again — only roll it back. If a partial APISIX publish failure occurs mid-operation, the system attempts to restore the previous traffic split automatically rather than leaving traffic half-switched — if you see a promote/rollback error, re-check the deployment’s actual current traffic state via List BG rather than assuming it’s stuck.

Lifecycle transition rejected: “lifecycle transition from … to … is not allowed”

API and API Version lifecycle status only moves forward through a fixed chain: draft → review → published → deprecated → retired, with review allowed to step back to draft. You cannot, for example, jump draft straight to published, or move a retired item anywhere. Use Production Approvals to move a review version to published.

Rate limit / quota policy rejected

requests_per_second must be ≥ 1 and burst ≥ 0 for rate limits; requests must be ≥ 1 and window_seconds ≥ 1 for quotas. A value of 0 or blank for the “enabled” limit fields will fail validation rather than silently disabling the limit — use the enabled checkbox/toggle to actually turn a limit off.

Developer Portal

You’re pointed at a control plane where passwordless email login isn’t enabled (production, or any environment not explicitly configured for it). This is intentional — production requires real identity verification. Confirm you’re using the intended URL, or ask your platform admin how to sign in in this environment.

The portal watches for 401 responses and automatically signs you out when one occurs — there’s no distinct “your session expired” message from the backend, because the 401 body is identical whether the token is missing, expired, or malformed. In practice this happens when your 8-hour session token has expired. Just sign in again.

“Select an API from the catalog before creating an application”

Create Application in the top nav needs to know which environment to create the application in, and infers it from an API you’ve already viewed or searched for. Browse the Catalog and open (or search to reveal) at least one API first, then retry, or use Create App & Request Access directly from a catalog card instead.

“Access request already exists (pending/approved)”

You (or the one-click Create App & Request Access flow) already have a request in flight for that exact application + API pair. Check My Applications → Access Requests for its current status rather than resubmitting.

Creating a credential fails even though your access request shows “approved”

Credential creation requires an approved access request for that specific application against that specific catalog entry — if you created a different application after the approval, or you’re trying to create a key against a different API than the one approved, it will fail. Use Show Keys / Hide Details on the correct application to confirm the approved request lines up.

API Test Console goes blank after clicking Send Request

In current builds, clicking Send Request in the Test console can leave a blank white screen rather than showing the response panel described in the Developer Portal Guide. Reload the portal and sign in again to recover. Treat this as a known issue rather than a configuration mistake if it happens to you.

A subscription doesn’t seem to grant access

Only subscriptions with status Active grant access — Suspended and Cancelled subscriptions exist in the list but have no effect. Also, a subscription can only be created when the application and the plan’s product belong to the same environment; if you don’t see a plan under a product, the mismatch is a likely cause.

Still stuck?

Admins: use the Operations tab’s Active Alerts and Publish Operations panels — failed publish operations record an error_message you can inspect directly.
Both apps: open your browser’s network tab — the response body for a failed request is almost always {"error": "<the exact message shown in the banner>"}, so there’s rarely additional hidden detail to dig for.