Response format
Errors always follow this pattern:
{
"ok": false,
"error": "invalid_token"
}
The error value is a stable key (do not rely on message text).
Common error codes
| HTTP | error | Meaning | Typical fix |
|---|---|---|---|
| 400 | invalid_json |
Body is not valid JSON | Send Content-Type: application/json and valid JSON |
| 401 | missing_token |
No Bearer token provided | Add Authorization: Bearer ... |
| 401 | invalid_token |
Token invalid, disabled, or expired | Use a valid active token; check is_active/expires_at |
| 401 | unauthorized |
Auth failed (generic) | Check token format and server time/DB |
| 403 | forbidden_scope |
Token scope not allowed for this endpoint | Create token with correct scope, or update permissions |
| 404 | not_found |
Endpoint not found | Check the URL and method (GET/POST) |
| 500 | pdo_not_available |
Database connection missing/unavailable | Check DB config and bootstrap |
| 500 | server_error |
Unhandled server error | Check logs; reproduce with a minimal request |
Recommended client behavior
- Do not display raw error keys to end users; translate in the app UI.
- Retry only when it makes sense (e.g., network timeouts), not on
invalid_token. - Log the request id (if you add one later) and the error key for support.