Last updated on August 26th, 2026 at 11:48 am
The main lesson: a working web portal does not prove that the product’s API service is available. They can share one address while using different services behind the scenes.
If an API request returns 502 Bad Gateway, start by checking the API gateway and its upstream service. Do not assume the request body or credentials are the first problem.
What I learned
A gateway is a front door that forwards requests to another service. The browser portal may be handled by one upstream service, while API paths are forwarded to a separate API component.
This creates a confusing result: the login page loads normally, but every API call returns 502.
What a 502 usually means
A 502 response means the gateway could not get a valid response from the upstream service. Common causes include:
- The API component is not installed.
- The API service is stopped or unhealthy.
- The gateway route points to the wrong host or port.
- A required integration module is not enabled.
- A firewall blocks the gateway from reaching the upstream service.
A practical troubleshooting order
- Test one minimal endpoint. Use the smallest documented health, version, or resource-list request.
- Read the HTTP status first. A 502 points toward gateway-to-upstream communication. Authentication problems more commonly return 401 or 403 after the API service responds.
- Check installed components. Confirm that the API gateway and its translation or integration service are installed, enabled, and licensed where required.
- Check service health. Verify the API-related processes are running and inspect their recent logs.
- Check the route. Confirm the gateway sends the API path to the correct internal service and port.
Minimal test pattern
curl -i -X POST 'https://API_HOST/API_HEALTH_ENDPOINT' -H 'Content-Type: application/json' -d '{}'
Use the endpoint from the product’s documentation. Keep the first test small so malformed application data cannot hide the infrastructure problem.
Common mistakes and fixes
- Cause: assuming a valid license starts every optional service. Fix: verify the API component is installed and running.
- Cause: changing request signatures while receiving 502. Fix: restore a minimal request and check the upstream service first.
- Cause: treating a working portal as proof that the API route works. Fix: test the API path independently.
- Cause: disabling certificate checks and expecting the 502 to disappear. Fix: solve certificate trust separately from the upstream gateway failure.
Conclusion
A web portal and an API can fail independently even when they use the same hostname. The next action is to verify that the API upstream service is installed, running, and reachable from the gateway before debugging credentials or request payloads.