Two lookup tables: one for things that go wrong in the dashboard or mobile app, one for API error codes. Find your symptom, apply the fix, and if it doesn't resolve, contact support with the details the table mentions.
Dashboard and mobile
| Symptom | Likely cause | What to do |
|---|---|---|
| Can't sign in to the dashboard | Invitation not yet accepted, or wrong password | If you were invited, open the invitation email and follow the link to set a password first. Otherwise use Forgot password on the sign-in page to reset. |
| Can't sign in to the mobile app | Same credentials as the dashboard | Verify you can sign in on the web first. If the dashboard works and the app doesn't, check the device's connection and try again. If the password is the problem, type your email on the app's sign-in screen and tap Forgot your password? — the reset link opens in the phone's browser. |
| Form missing on a device | Form not published or not assigned to you, or sync pending | Confirm the form was published and assigned to your user. Then tap the sync icon, or sign out and back in to force a sync. |
| Form on the device looks outdated | Edits not yet published | Edits after publishing stay in the draft. Publish again, then refresh the form list on the device. |
| Record submitted on a phone but not in the dashboard | Device still offline; record queued locally | Reconnect the device and open the app — queued records upload on their own, and the sync icon's amber dot clears when the last one leaves. Tap the sync icon to try immediately. If the record still hasn't arrived, sign out and back in. |
| Password reset email didn't arrive | Wrong address, or filtering | Check spam, and confirm the address matches your user record. Ask an administrator to verify the address on file. |
| Invitation link doesn't work | Invitation expired or already used | Ask an administrator to send a fresh invitation. |
API error codes
These are the error.code values from the response envelope. Every error response carries a request_id — quote it when reporting an issue.
| Code | HTTP | What to do |
|---|---|---|
validation_failed | 400 | The body or query is malformed. Check error.details for the failing field and fix the request. Writing a form also returns this when the field tree does not match the field reference, and publishing returns it when the draft is structurally invalid or contains a circular expression. |
unauthorized | 401 | The API key is missing, expired, or revoked. Verify the Authorization: Bearer header and the key's status in the dashboard. See authentication. |
forbidden | 403 | The key is valid but lacks the required scope, or it's an organization-scoped key addressing a different organization. The required scope is echoed in the error message — mint a key with it. |
not_found | 404 | The resource id or path doesn't exist, or isn't visible to this key. This also covers an id inside the body that points at nothing — an organization_id or report_id on a create, for example. Check the id and the key's organization binding. |
conflict | 409 | A slug or identifier already exists, or an idempotency key was replayed with a different body. Use a new identifier, or a new idempotency key for a genuinely new request. See idempotency. |
rate_limited | 429 | The key's request budget is exhausted. Back off and retry per the recipe in rate limiting. |
internal_error | 500 | Unexpected server fault. Retry idempotent operations with backoff. If it persists, report the request_id. |
bad_gateway | 502 | An upstream call failed (for example a report merge). Retry with backoff; report the request_id if it keeps failing. |
degraded | 503 | Returned by /health when the database is unreachable. Treat it as an active incident — retry later and watch health and uptime guidance for monitoring. |
For the full request and response shapes around these codes — envelopes, details, request ids — see conventions.