Docs / Error codes
Error codes
Errors are JSON: {"error": "human message", "code": "machine_code"}. Status semantics: 401 the key is unusable · 403 the key is valid but not allowed here · 402 plan limit · 429 slow down.
API (/v1/*)
| status | code | meaning / what to do |
|---|---|---|
| 400 | invalid_target | Specify exactly one notification target: webhook_url or telegram: true. |
| 400 | telegram_not_bound | telegram: true requires Telegram connected in the console first. |
| 400 | — | Invalid body: bad TRON address, malformed JSON, or a webhook URL that fails validation (non-http(s), credentials in URL, private/reserved IP range, unresolvable host). |
| 401 | missing_api_key | No Authorization: Bearer tw_… header. |
| 401 | invalid_api_key | Malformed or unknown key. Check for truncation/whitespace. |
| 401 | revoked_api_key | Key was revoked (timestamp included). Create a new one in the console. |
| 402 | quota_exceeded | Active-watch quota reached. Response includes usage: {active_watches, limit, plan}. Delete a watch or upgrade. |
| 403 | wrong_network | Key bound to the other network (tw_test_ ↔ tw_live_). The message names the key you should use. |
| 404 | — | Resource not found or not yours (we don't distinguish). |
| 409 | — | A watch with the same address + filter + channel already exists. |
| 429 | rate_limited | Plan rpm exceeded. Honor Retry-After; check X-RateLimit-Remaining to self-pace. |
| 500 | — | {"error":"internal server error"} — our fault, no internals leaked. Retry with backoff; check /healthz. |
Console (/console/*, session auth)
| status | code | meaning |
|---|---|---|
| 401 | no_session | Not signed in (or session expired — 7-day sliding window). |
| 403 | csrf_mismatch | X-CSRF-Token header missing or not matching the csrf cookie. |
| 409 | telegram_watches_active | Unbind blocked: delete your active Telegram watches first. |
| 429 | login_rate_limited | 5 failed logins / 15 min (per IP + email). Wait it out. |
| 503 | telegram_unavailable | Telegram bot not configured on this deployment. |
Webhook delivery outcomes
Not errors you receive, but states you'll see in the console and GET /v1/events:
| delivery.status | meaning |
|---|---|
PENDING | Queued or between retries (schedule: 1m/5m/30m/2h/6h after the immediate attempt). |
DELIVERED | Your endpoint (or Telegram) acknowledged. |
DEAD | All 6 attempts failed — inspect per-attempt response codes in the console, fix your receiver, reconcile via the events API. |