Help Guides
Troubleshooting
Find the message you're seeing, then do what the last column says. For questions rather than errors, see the FAQ.
Signing in
| You see | Why | What to do |
|---|---|---|
| "That email and password don't match." | Wrong email or password. | Check both, or use Forgot password? |
| "Too many attempts." | Too many tries in a short time. | Wait a few minutes, then try again. |
| "This account is suspended." | An admin suspended the account. | Contact your Substratal admin. |
| "That code didn't work." | The two-factor code is wrong or has expired. Codes change every 30 seconds. | Make sure your device's clock is set automatically, then enter the current code, or use a recovery code. |
| "That took too long. Sign in again." | The two-factor step has a 5-minute limit. | Sign in again. |
| "This test account has expired." | Test-mode users stop working at their expiry time (24 hours by default). | Create a new test user, or ask someone with users.manage to extend it. |
| You're asked to sign in again unexpectedly | Your session ended: you chose Sign out everywhere on another device, an admin ended it, you didn't use the app for 30 days, or 90 days passed since you signed in. | Sign in again. |
Update notices
| You see | Why | What to do |
|---|---|---|
| Update available, with a date | The API is retiring the version this app was built for. You have at least 6 months. | Update the app. |
| Update required | The API no longer supports this app's version. The app stops calling the API. | Update the app. |
See API versioning for how versions and deprecation work.
Anywhere in the apps
| You see | Code | What to do |
|---|---|---|
| A section or button is missing | — | Your account doesn't have the permission. See Roles and permissions. |
| A button is greyed out | — | You can see this but not change it right now. Hover over it, or long-press it, for the reason (for example "Seed roles can't be edited"). |
| "You don't have permission…" | 403 |
Your permissions changed while you were working. The app refreshes them. Ask an admin if you need more. |
| "Someone else changed this…" | 409 version_conflict |
Another person saved the same thing first. The app reloads it; make your change again. |
| "Too many requests." | 429 |
The app slows down by itself. Wait a moment. |
| "Substratal is briefly unavailable." | 503 |
Maintenance or an outage. The app retries; check back in a few minutes. |
| "Couldn't reach Substratal." | — | Check your network. If you use a VPN or a proxy, make sure it allows api.substratalapps.com. |
Reporting a problem
Report the screen ID (for example USR-01, shown on every screen), what you did, and roughly when. Every API response carries a request ID (req_…) that support can look up. Never include passwords, tokens, recovery codes or API key secrets.
For developers
The API's error format and every error code are in Conventions → Errors. The two version errors:
400 api_version_required: the request had noSubstratal-Versionheader. It's always a bug in the client.400 unsupported_api_version: the header names a version the API doesn't serve.details.supportedlists the ones it does.
Calls to https://api.substratalapps.com/v1/… return 404: paths have no version prefix any more. Send the header instead.
Screens in this guide
AUTH-01 · Sign in AUTH-02 · Two-factor challenge GLB-03 · System states