Errors
Known aiogram-webhook errors are converted into safe public JSON responses. Detailed diagnostic messages are logged through the library logger.
| Condition | Status | Body | Start with |
|---|---|---|---|
| Invalid JSON payload | 400 |
{"detail": "Bad request"} |
Request body and client. |
| Security check failed | 403 |
{"detail": "Forbidden"} |
Security. |
| Secret token failed | 403 |
{"detail": "Forbidden"} |
Secret token. |
| Route does not match (bad/missing path or query params) | 404 |
{"detail": "Not found"} |
Route. |
| Target cannot be resolved | 404 |
{"detail": "Not found"} |
Route and Engines. |
| Bot cannot be resolved | 404 |
{"detail": "Not found"} |
Selected engine and bot registration. |
| Shutdown already started | 503 |
{"detail": "Service unavailable"} |
Engine startup/shutdown behavior. |
Route.match() failures (missing/invalid path params, missing/mismatched/unexpected query params) all raise RouteMatchError subclasses and share the same 404/{"detail": "Not found"} response as an unresolved target, but occur earlier in the pipeline, before target/bot resolution.
Error boundary
The public response intentionally stays short:
{"detail": "Forbidden"}
The log message carries more detail so you can debug the actual component that rejected the request.
Common causes
The request body is not valid JSON. Telegram normally sends valid JSON, so this often means a non-Telegram client called the endpoint.
A configured secret token or security check rejected the request. Check X-Telegram-Bot-Api-Secret-Token, client IP, and proxy headers.
Route.match() failed (missing/invalid path or query params), or the engine could not resolve a target or bot. For TokenEngine, verify that {bot_token} is present, valid, and registered when required.
The engine is shutting down. This is expected during graceful worker termination.
Where to start
- Check the HTTP status.
- Open the matching component page.
- Check application logs for the detailed message.
- Use troubleshooting when the component looks correct but the behavior is still wrong.