Developer Troubleshooting
Common developer-facing issues and how to diagnose them — API auth failures, missing AI output, integration and webhook problems, and permission errors.
#Purpose
Give developers a fast path from symptom to cause using real system signals.
#Architecture
Most developer issues map to a dependency (auth, AI, email, an integration) or to permissions/RLS. The health and status surfaces plus the log tables are the primary diagnostic tools.
#How it works
1
Reproduce
Trigger the failing request and capture the error code and status.
2
Check the dependency
Use the relevant status signal (AI, email, Stripe) or logs.
3
Check permissions
Confirm the caller's role and organization scope.
4
Fix and verify
Correct the cause and re-run against health/status.
#Reference
#Symptom → cause
| Symptom | Likely cause |
|---|---|
| 401 invalid_api_key | Key wrong/revoked/expired — rotate or reissue |
| 403 insufficient_scope | Key lacks the scope — reissue with it |
| 429 rate_limited | Exceeding ~120/min per key — back off |
| AI returns nothing | Workspace AI access not configured |
| Emails not sending | No email provider configured (default none) or SMTP stub in use |
| Webhook not received | Endpoint inactive, wrong URL, or event not subscribed; check deliveries |
| 403 forbidden in app | Role lacks permission; RLS/role check denied the action |
#Implementation notes
- The public API rejects revoked/expired keys and enforces scopes.
- Email requires a configured provider (Resend); SMTP is a stub.
- Webhook deliveries retry with backoff and can dead-letter.
#Limitations
Known limitations
- Sandbox/static checks cannot reproduce live dependency failures.
- Some issues require admin access to inspect status and logs.
#Security considerations
Security
- Never log secrets while debugging.
- Verify identity before assisting with access recovery.
- Restrict access to logs and status endpoints.
#Best practices
- Start from the error code and the matching dependency signal.
- Reproduce with a minimal request.
- Check RLS/role first for permission errors.
#Related documentation
Still need help?
Can’t find what you’re looking for? The DevSphere OS team is happy to help.
Was this page helpful?