Every analytics tool wants a subscription. And your data. I built Twiligent instead. YouTube stats. Instagram stats. One dashboard. Runs locally on your machine.
Error Handling Standards
Every backend failure is a typed error thrown where the problem is found and formatted in one place. docs/architecture/backend/REQUEST_PIPELINE.md has the full table of errors, codes and statuses.
Typed Errors (backend/lib/errors.ts)
| Error | Code | Status | Throw when |
|---|---|---|---|
ValidationError |
VALIDATION_ERROR |
400 | Input is missing or malformed, or a stored field the request needs is missing |
UnauthorizedError |
UNAUTHORIZED |
401 | No token, or an invalid or expired one (thrown by requireAuth), or a Send Email hook call without a valid signature (thrown by verifyAuthHook) |
ForbiddenError |
FORBIDDEN |
403 | Reserved; another user's record is a NotFoundError |
NotFoundError |
NOT_FOUND |
404 | The record does not exist for this user, or is on the wrong platform |
ConflictError |
CONFLICT |
409 | The account is already added, found by the list check or, for an add at the same moment, by the unique index (isUniqueViolation) |
RateLimitedError |
RATE_LIMITED |
429 | A daily allowance is used up: the auth email caps in authEmailService.ts. Per-request limits are the rate limiter's job, not this error |
UpstreamError |
UPSTREAM_ERROR |
502 | YouTube, Instagram or Resend answered with an error |
NotConfiguredError |
NOT_CONFIGURED |
503 | A Worker secret the request needs is not set, or a core Supabase secret is missing (thrown by injectClients for every request) |
UpstreamTimeoutError |
UPSTREAM_TIMEOUT |
504 | A platform call was cancelled or timed out |
DatabaseError |
DATABASE_ERROR |
500 | A Supabase query failed or passed the 15 second database timeout (thrown by repositories/query.ts) |
An error carries a code, not a status; middleware/errorHandler.ts maps the code to the status. Anything that is not an AppError becomes INTERNAL_ERROR (500).
Layer-by-Layer Rules
Platform API Calls (services/youtube/, services/instagram/)
Throw an UpstreamError as soon as the platform returns an error, keeping the platform's own wording (users can act on it) and its reason and status:
const data = await response.json() as T & YouTubeApiErrorBody;
if (data.error) {
throw new UpstreamError(data.error.message, { reason: data.error.errors?.[0]?.reason || '', status: data.error.code });
}
Each platform's request helper (ytFetch, igFetch and igPost) runs its call through a circuit breaker (lib/circuitBreaker.ts, one per platform and Worker isolate). Five outages in a row, meaning a timeout the caller did not cause, an unreachable host or a 5xx, pause calls for 30 seconds: they fail at once with an UpstreamError (reason unreachable, so a scheduled post that meets it is retried) whose message says to try again in a minute. One trial call then decides whether the platform is back. A 4xx, such as an expired token, never opens it, and Instagram's Graph error codes are not read as HTTP statuses. Comment replies (instagramMessaging.ts) keep their own cooldowns and do not use it.
UpstreamError passes its message through redactSecrets (lib/redact.ts), which removes URLs, Bearer tokens and token-like name=value pairs and JSON fields, because a platform error can echo the request URL, a header or the form body with the API key or token in it. Cast the parsed JSON once to an interface that covers the fields the module reads (see docs/guidelines/TYPESCRIPT.md).
Pass the request's AbortSignal to every fetch. A cancelled or timed out call becomes an UpstreamTimeoutError; a network failure an UpstreamError:
try {
response = await fetch(url.toString(), { signal });
} catch (err) {
if (isAbortError(err)) throw new UpstreamTimeoutError('YouTube', err);
throw new UpstreamError(`YouTube could not be reached (${(err as Error).message})`, { cause: err });
}
Database Calls (repositories/)
Run every query through execute, rows or maybeRow in repositories/query.ts. A thrown error or a returned Supabase error becomes a DatabaseError named after the operation:
const found = await rows<AccountRow>('accounts.listForUser', () => db.from('accounts').select(COLUMNS).eq('user_id', userId));
The client gets a plain message (The database request failed. Try again in a moment.); the driver's message, which can name tables and constraints, goes to the log only. Every Supabase call has a 15 second timeout (DB_TIMEOUT_MS in database/supabase.ts, the client's db.timeout), so a query that hangs becomes a DatabaseError well inside the 30 second request deadline instead of holding the request. A query that finds nothing is not an error: maybeRow returns null and the service decides whether that is a NotFoundError.
Cache Operations (repositories/analyticsCacheRepository.ts)
Always catch and fall back silently - cache failures must never surface to users. Every catch returns an explicit fallback with a one-line reason, so no catch block is empty:
try {
return await redis.get<T>(key);
} catch {
// a cache miss falls back to the live api
markDown();
return null;
}
The repository keeps this in three private helpers (readKey, writeKey, deleteKey) that every method uses. Do not log cache errors - they create noise for transient Redis connection issues.
Services (services/*Service.ts)
Services hold the rules, so they throw most errors: NotFoundError when a ...ForUser lookup returns null, ValidationError when a stored field the call needs is missing or a business rule fails, ConflictError for a duplicate, NotConfiguredError when a Worker secret is not set. Let platform and database errors propagate unchanged, with one exception: an insert that breaks a unique index (isUniqueViolation(err) in lib/errors.ts, Postgres code 23505) is a duplicate the service already has a message for, so it becomes that ConflictError.
Catch only when one failure must not stop other work, and say why:
// one failure must not stop the rest; results line up with the accounts by index
const settled = await Promise.allSettled(listed.map(account => refreshListed(userId, account)));
Controllers (controllers/)
Controllers do not catch errors. A thrown error goes straight to the error handler:
export const getInstagramMedia = controller.createHandlers(queryParams(parseFreshQuery), async c => {
const result = await servicesFor(c).instagramAnalytics.media(c.get('userId'), pathParam(c, 'id'), c.req.valid('query'));
return c.json({ success: true, ...result } satisfies InstagramMediaResponse);
});
The one exception is the Instagram OAuth callback, which catches every error and redirects the browser back to the accounts page with ig_error, because the user arrives there from Instagram, not from the app.
Global Error Handler (middleware/errorHandler.ts)
Registered with app.onError(errorHandler) and app.notFound(notFoundHandler). It is the only place a failure becomes a response:
{ "success": false, "code": "NOT_FOUND", "message": "Account not found", "requestId": "3f2a..." }
It also maps Hono's own HTTPException (such as a malformed JSON body) by status, and answers anything else with INTERNAL_ERROR and a message asking the user to quote the request id. The rate limiter builds its 429 body with the same errorBody() helper, plus retryAfter.
authHookErrorHandler, in the same file, is used only by routes/authHookRoutes.ts (router.onError). It logs and maps statuses exactly like errorHandler, but writes the body Supabase Auth reads from a hook, { "error": { "http_code": 429, "message": "..." } }; Supabase passes the message to the sign-in page, so it is written for the person signing in or up; for the daily cap the page shows its own wording (emailErrorNotice in frontend/src/lib/authErrors.ts).
Where the Frontend Shows a Failure
Put the message next to its cause, so it is still there when the person looks for it (WCAG 3.3.1, 3.3.3):
| Failure | Where it shows |
|---|---|
| A field the person can fix (empty, wrong format, too short, a date in the past) | Under the field, through FieldRow error, which sets aria-invalid and aria-describedby; on submit, focus moves to the first invalid field. Validators return the field and the message, not only a message |
| A load that failed | ErrorState with Try again in place of the content, or an inline Alert above the last good data; never an empty state |
| Part of a load that failed (one channel of five) | An inline Alert naming what did not load, with Retry, above the results that did |
| A request that failed after submit (network, server, a platform refusing) | A toast; error toasts stay until closed |
A toast is never the only copy of an error the person has to act on. Success toasts confirm in past tense and close on their own.
Frontend API Calls
Catch in the component or handler, show a toast for a request failure, and handle loading state:
const [loading, setLoading] = useState(false);
const { showToast } = useAppContext();
async function handleSubmit() {
setLoading(true);
try {
await api.doSomething(data);
showToast('Settings saved');
} catch (err) {
showToast((err as Error).message, 'error');
} finally {
setLoading(false);
}
}
The api.ts request() function throws an Error for any status outside 2xx, with the message from failureMessage(status, body) in frontend/src/lib/apiErrors.ts: the backend's message, plus (request <id>) on a 5xx so the user can quote it. A 2xx response is always a success, so callers never check success. See docs/architecture/frontend/API_LAYER.md.
Logging
Log through lib/logger.ts: services use context.log, middleware and controllers use requestLogger(c). Each call writes one JSON line with the level, message, request id, user id and any fields:
log.error('scheduled post failed', { postId: post.id, ...errorFields(err) });
errorFields(err) adds the error's message and cause through redactSecrets (URLs, Bearer tokens and token-like parameters removed), never the stack. The error handler already logs every failed request (500 and above at error, 4xx at warn), and requestContext writes one access line per request, so do not log an error you are about to throw. Never call console directly.
Do not log sensitive values: access tokens, API keys, cookies, user emails, Supabase URLs. Redaction is a safety net for text you do not control, such as a platform's error message; it is not a reason to pass a secret to the logger.
Detecting and Recovering
GET /api/health is the liveness check (the Worker answers) and GET /api/health/ready the readiness check (the Supabase secrets are set and the database answers, with databaseMs). A missing core secret is a NOT_CONFIGURED 503 that names it, for requests, and a cron run skipped log line, for cron runs. docs/workflows/RECOVERY.md lists what to do when production breaks: find the failing request by its id, pause automation, roll back, and back up the data.
User-Facing Error Messages
Backend errors should be descriptive but not expose implementation details:
- Good:
'Account not found','This channel is already added','scheduledAt must be a valid future date' - Bad:
'supabase error: duplicate key value violates unique constraint accounts_pkey'
Say what went wrong and what to do ('No access token stored - reconnect this Instagram account'). When the platform API returns a message that is end-user readable, UpstreamError passes it through. Database driver messages never reach the client.