Docs
Apache APISIXReleases and supportTroubleshootingCommon HTTP errors

Common HTTP errors

Troubleshoot common HTTP errors returned by Apache APISIX: 404, 401/403, and 502/503/504.

This page describes the symptoms, causes, checks, and resolutions for the most common HTTP error status codes APISIX returns.

404 Not Found

Symptoms

  • The client receives 404 Not Found.
  • The request does not match any configured route, service, or upstream.

Likely causes

  • The route does not exist or is disabled.
  • The request path, host, or method does not match the route definition.
  • The apisix data plane is not in sync with the latest configuration.

Checks

[TODO] Add commands to list routes, services, and upstreams and to verify the active configuration.

Resolution

[TODO] Add steps to verify route match conditions, enable the route, and force a configuration sync.

Verification

[TODO] Add a curl or test request to confirm the route returns 200.

Escalation data

  • APISIX version
  • Full request URL and headers
  • Output of GET /apisix/admin/routes
  • etcd connectivity status

401 Unauthorized and 403 Forbidden

Symptoms

  • The client receives 401 or 403.
  • Authentication or authorization plugins are configured on the route.

Likely causes

  • Missing, invalid, or expired API key/token.
  • Consumer is not associated with the required consumer group.
  • IP restriction, referer, or other access-control plugin blocks the request.

Checks

[TODO] Add commands to verify the consumer, credential, and plugin configuration.

Resolution

[TODO] Add steps to rotate or re-enable credentials, bind consumers, and adjust access-control rules.

Verification

[TODO] Add a test request with a valid credential.

Escalation data

  • Enabled authentication/authorization plugins
  • Consumer and credential IDs
  • Request headers and source IP

502 Bad Gateway, 503 Service Unavailable, and 504 Gateway Timeout

Symptoms

  • The client receives 502, 503, or 504.
  • APISIX cannot connect to or receive a timely response from the upstream.

Likely causes

  • Upstream service is down or overloaded.
  • Upstream DNS resolution fails.
  • Upstream TLS/misconfiguration.
  • Upstream timeout is too short.
  • Connection pool is exhausted.

Checks

[TODO] Add commands to verify upstream health, DNS, TLS, and connection pool status.

Resolution

[TODO] Add steps to restart or scale the upstream, adjust timeouts, and verify TLS settings.

Verification

[TODO] Add a direct upstream health check and a test through APISIX.

Escalation data

  • Upstream node list and health-check results
  • Upstream error logs
  • APISIX access log with latency fields

Troubleshooting

Previous Page

etcd and configuration sync

Next Page