Getting Started FAQ
Common questions from teams getting started with Zerq. For broader troubleshooting, see the API Gateway section.
Why do I get 401 even with a token?
The token may be expired, signed by the wrong issuer, or sent without the expected header format. Re-check the profile auth method and token claims.
What causes 403 in Zerq?
403 means identity is valid, but policy denies access. Most common causes: wrong X-Client-ID, wrong profile binding, or missing role/scope.
Why am I seeing 405?
The proxy route does not publish that HTTP method. Confirm method list on the route and re-publish.
When should I expect 429?
When client/profile quotas are configured and your request rate exceeds the limit window.
What headers should I include in test calls?
For protected routes, include Authorization, X-Client-ID, and X-Profile-ID where profile selection is required.
curl -i "https://gateway.example.com/v1/sample" \
-H "Authorization: Bearer $TOKEN" \
-H "X-Client-ID: docs-sandbox" \
-H "X-Profile-ID: sandbox"
Where do I debug request failures?
Start with request logs for runtime behavior, then audit logs for recent config changes.