Troubleshoot an API request
First identify where you saw the error. A failed login screen, an unreachable local return address and a rejected API command need different checks.
| Where it happened | Start here |
|---|---|
| Signing in to the SyAuth dashboard or activating a plan | Dashboard/account access |
After clicking Approve, the browser goes to localhost or 127.0.0.1 | Check that the app or manual test receiver is still running at the registered return address |
| Waiting for a verification or password-reset email | Email delivery checks |
A terminal says command not found or cannot find the script file | Check the local tool installation and file path in the walkthrough; the request may not have reached SyAuth at all |
| A command returns a numbered HTTP status and JSON text | Use the response table below and the exact error text |
For a request that reached the service, keep the exact URL, HTTP method, status and response body. In the curl examples, -i prints the status and headers above the JSON body. A developer can reproduce the smallest request from the affected app/server and compare it with the relevant walkthrough; the first workspace request checks management credentials specifically.
| Symptom | Next check |
|---|---|
TLS error, BAD_RECORD_MAC or empty response before any HTTP status | Compare TLS versions and networks; see TLS diagnostics and the temporary TLS 1.2 workaround. |
| Missing/invalid API key on signup | /register/ needs a registration key in X-API-Key, not a workspace or developer token. |
| 401 on a management request | Use X-Developer-Token; check expiry and revocation. |
| 401 on a profile request | Use the application login token in Bearer authorization, not a developer token or OAuth ID token. |
| Unexpected 401 on MFA, SCIM or SAML | Check known limitations; report the endpoint and sanitized response. |
| 403 | Check required scope, plan/feature access, resource owner and workspace membership. |
| 400 with field errors | Match the operation schema; supply workspace/client context and the exact field names. |
| OAuth invalid_client | Use public client_id, correct client type, and server-side secret for a confidential client. |
| OAuth invalid_scope | Use scope names enabled on this OAuth client; separate requested scopes with spaces. Developer-token scopes such as read_users are separate permissions. |
| OAuth unauthorized_client | Enable the grant used by this request on the client; use a confidential client for client credentials. |
| OAuth invalid_grant | Code may be expired/used; verify original redirect URI and PKCE verifier, then start a fresh attempt. |
| Redirect URI rejected | Match the registered callback exactly, including host, port, path and trailing slash. URL-encode it in the authorization query; use the original URI with --data-urlencode in the token request. |
| State or nonce validation fails | Compare with the values saved for this exact attempt. Do not regenerate them at the callback; restart sign-in if the saved attempt is missing. |
A return page shows Invalid or expired session after consent | For a no-app test, rerun the manual receiver and use its new URL and registered callback. For an existing app, start through its Sign in action and check the saved attempt/cookies. Keep the preceding failed response to distinguish a local check from a forwarded upstream error. |
| Browser cannot reach the callback | Start your app and confirm it handles the registered callback host, port and path. An example URI in the docs does not create that route. |
| Signup says the user already exists | Continue with verification/login for that user instead of repeating signup. Keep the same OAuth client context. |
| 404 | Check resource ID versus OAuth client ID, selected workspace and trailing slash. |
| 415 | Send the documented Content-Type; SCIM writes currently use application/json. |
| 429 | Reduce request rate and respect retry guidance returned by the service. |
| 5xx | Retry transient failures with bounded backoff; report persistent errors. Avoid blindly repeating a creation/payment request. |
| curl works, browser fails | Inspect Origin and preflight/CORS results; see application configuration. |
When contacting support, provide UTC time, method/path, status, sanitized body, workspace/client identifiers and whether the issue reproduces. Include a request/event ID if one was returned. Remove Authorization, cookies, API keys, passwords and email verification codes.
If you do not know the HTTP status or method, start with the action you took, exact visible error and final hostname/path. For example: “I ran the manual receiver, signed in and clicked Approve; the browser then showed this message at this address.” A sanitized response means you removed credentials and codes before sharing it. Include whether the callback receiver was running and whether you used its newly printed URL.