Skip to main content

Troubleshooting

Common errors when calling APIs through Zerq — with causes and fixes.

Gateway call errors​

StatusMost common causeWhat to checkHow to fix
400 Bad RequestMalformed request body or missing required parameterCheck the endpoint schema in the Developer PortalValidate your JSON body or query parameters against the schema
401 UnauthorizedToken missing, expired, or wrong formatCheck the Authorization header value and formatRe-copy the token from the profile detail; rotate if expired
401 (JWT)JWT signature invalid or claims wrongVerify the HMAC secret matches what Zerq has configuredEnsure the client_id and client_secret used for signing match the profile
401 (OIDC)Token issued by wrong IdP, or expiredCheck the iss claim matches the configured OIDC issuerObtain a fresh token from the correct identity provider
403 ForbiddenClient not assigned to collection, or profile inactiveCheck client collection assignment and profile active statusAsk your admin to assign the client to the collection or re-enable the profile
403 (IP blocked)Request IP not on profile allowlistCheck the profile IP restrictionsAsk admin to add your IP, or connect from an allowed network
403 (header)Wrong X-Client-ID or X-Profile-IDDouble-check both header valuesCopy directly from the Management UI or Developer Portal auth headers panel
404 Not FoundProxy not found or not publishedConfirm the path pattern and that the proxy is publishedCheck collection and proxy status in the Management UI
405 Method Not AllowedProfile allowed_methods restrictionConfirm the method is in the profile's allowed listAsk admin to update the profile, or use the correct method
429 Too Many RequestsRate limit or quota exhaustedCheck the Retry-After headerWait and retry; ask admin if quota needs to be increased
502 Bad GatewayUpstream service unreachableCheck upstream health and connection credentialsVerify the collection target URL is correct and upstream is running

Developer Portal sign-in errors​

SymptomCauseFix
Magic link email never arrivesEmail not on the client's authorized listAsk your admin to add your email to the authorized emails list on the client
Magic link says "invalid or expired"Link was used already or expired (links expire in 15 minutes)Click Send another link to request a fresh magic link
Signed in but no collections visibleClient has no collections assigned, or collections are unpublishedAsk admin to assign collections to the client and publish them
Profile selector is emptyClient has no active profilesAsk admin to create and activate a profile for your client
Portal access deniedhasPortalAccess is false on the clientAsk admin to enable Developer Portal access on your client record

Common debugging workflow​

  1. Copy the exact headers from the Developer Portal auth headers panel — avoid manual re-typing.
  2. Use the portal testing console — it auto-fills headers and shows the raw response.
  3. Check request logs — go to Logs → Request Logs and filter by your client ID; the log detail shows which check failed.
  4. Try a simple GET first to isolate auth issues from body/method issues.
  5. Rotate credentials if you suspect a token was compromised or expired.