Errors
Responses use JSON with error / error_description or JSON:API-style errors arrays.
Status codes
| Code | Meaning | Typical fix |
|---|---|---|
| 401 | Missing/invalid/expired token | Refresh via /oauth/token |
| 403 | Valid token, forbidden | Grant scope/permission; use user token if required |
| 400 | Bad request / validation | Fix body, filters, or required user |
| 404 | Unknown route or record | Check path, id, host/tenant |
| 501 | Feature/module disabled for this org | Enable on System → organization → Restfull Toggle tab |
| 422 | Semantic validation | See message (e.g. form errors) |
Common messages
| Message / situation | Remediation |
|---|---|
| Forbidden / CanCan denied | Add permission in System admin (proposals.draft, …) |
| User required | Use ROPC/impersonation token with resource_owner_id |
| User blocked / locked | Pick another user |
| Already voted | Idempotent vote handling on your side |
| Unknown order / filter | Match OpenAPI allowed values |
| Attachments API disabled | Restfull Toggle attachments_enabled for the organization |
Permissions debugging
- Confirm scope on token includes the route family (
proposals, …). - Confirm permission on API client matches the action.
- Confirm Host matches the organization that owns the client.