The short version

• A form route that calls the mail API and returns its result has one point of failure and no memory.
• When the key is missing or the provider is down, the visitor sees an error and the submission is gone. Nobody is notified, because notification was the thing that failed.
• Writing the submission to a table before the send attempt turns a total loss into a delayed reply.
• The fix is small. The bug is usually invisible until you go looking, because a form that fails this way leaves no trace of what it lost.

How the failure actually looks

This site's contact route had exactly this shape. It validated the payload, called Resend, and mapped the result to a status code. In production the API key was not set, so the route took its unconfigured branch and answered 503. When we checked in September 2026, every post to it got that 503.

The part worth dwelling on is what the failure left behind. The form did tell the visitor delivery was offline and showed our email address. On our side the failure left nothing behind: no row, no log line naming the visitor, no retry queue. If anyone tried to make contact, all they left was an absence — a form that had never produced a single lead, which reads exactly like a form nobody uses.

That ambiguity is the real cost. "No leads" and "no leads that survived" look identical from the inside.

Capture and notification are different jobs

They fail for different reasons, they have different consequences, and they should not share a code path.

Capture is a write to storage you control. It should happen as early as possible, before any optional work, and it should never be able to take down the request.

Notification is a call to somebody else's service. It will fail sometimes. That is a fact about the world, not a bug to be eliminated.

Once they are separate, the question at the end of the request changes. It stops being "did the email send?" and becomes "is the lead safe?" — and the answer to the second question is the one that decides what the visitor should see.

// Capture first, notify second.
const stored = hasLeadStore() ? await recordLead({ ... }) : "NOT_CONFIGURED";
const captured = stored === null;

if (!hasEmailConfig()) {
  // The lead is safe even though nobody has been told yet.
  if (captured) return NextResponse.json({ ok: true });
  return NextResponse.json({ ok: false, error: "EMAIL_NOT_CONFIGURED" }, { status: 503 });
}

The route only returns an error when the submission is genuinely lost — when neither the store nor the mail provider took it. A failure the system has already absorbed is not the visitor's problem to solve.

Make the capture unable to throw

A storage helper that throws moves the fragility rather than removing it. recordLead returns null on success or a short error code, and never raises:

export async function recordLead(lead: LeadRecord): Promise<string | null> {
  const config = storeConfig();
  if (!config.url || !config.key) return "NOT_CONFIGURED";
  try {
    const response = await fetch(url, { method: "POST", headers, body });
    if (!response.ok) return `STORE_${response.status}`;
    return null;
  } catch (err) {
    return err instanceof Error ? err.message : "UNKNOWN_STORE_ERROR";
  }
}

The trap this creates, and how to close it

Never throwing is the right call, and it introduces a new way to fail quietly. If the store rejects the write — a wrong key, a wrong project, a missing grant — and the email happens to succeed, the route returns 200, the visitor is thanked, and the lead survives only as an email. The durable copy you built the store for does not exist, and nothing tells you.

So the store's refusals need a detector:

if (stored !== null && stored !== "NOT_CONFIGURED") {
  console.error("[contact] lead store failed", { stored });
}

"Not configured" is a deliberate state and stays quiet. "Configured and refused" is a misconfiguration somebody has to see.

How to tell whether yours is working

A 200 from the endpoint is not evidence. While email is working, a misconfigured store returns the same 200 as a healthy one — that is the whole point of the design, and it is also why the response cannot be the test.

Select the row. Post one submission with a synthetic address, then query the table directly and confirm it arrived, with the fields you expected. If you only check the status code, you are testing the part that was never going to fail.

What this does not solve

Durable capture protects the lead. It does not deliver the email, and it does not tell the prospect you will be slower than usual. If the provider is down for a day, you have the submissions and you still have not replied to any of them — which is better than the alternative and is not the same as working.

It also raises the value of the store. Once submissions land in a table instead of an inbox, that table holds contact details you are responsible for: enable row-level security, give it no public policies, and let only the server's key write to it. Supabase's secret and service_role keys bypass row-level security, so that key belongs on the server and nowhere else (Supabase, API keys). A lead store that anyone can read is a worse outcome than the bug you started with.

The short version

• Validation failures are not submissions. Counting them makes a user's own mistakes exhaust their allowance.
• Honeypot trips should count, so an address that trips the honeypot is throttled sooner on everything else it sends.
• So the order is: honeypot, then validate, then limit. Not limit, then everything else.
• If a throttled request is answered like a success — a reasonable design, to stop callers mapping the limit — then this ordering bug is silent by construction. That is what makes it worth checking rather than assuming.

How the bug is born

You add a limiter to a public POST route. The obvious place is the top of the handler, before the work: refuse early, spend nothing. That instinct is right for expensive work and wrong here, because the first thing after it is validation, and validation rejects things that were never submissions.

We wrote exactly this. The route took a unit, then validated, then processed. An adversarial review caught it before it reached anyone.

The detail that made it real rather than theoretical: the form is rendered with noValidate, so the browser does not block a malformed attempt — every submit reaches the server and every rejection is a server-side 400. Five of those in a minute is not a stretch. An empty name, a bad email address, then a message under the minimum length three times. The sixth attempt, the one that was finally correct, would have hit the limit.

What the visitor would have seen

This is the part that turns a design mistake into a lost lead. Throttled requests were answered with the same status and body as success, deliberately, so that a caller could not map the limit by watching responses.

Applied to a valid submission that was refused, the same design says: 200, "Message received", no row in the database, no email to anyone. The visitor believes they have made contact. Nobody has any record that they tried.

It also defeats the obscurity it was built for

There was a second consequence, and it undoes the reason the responses were made identical in the first place.

Throttled plus invalid returned 200. Unthrottled plus invalid returned 400 VALIDATION. So anyone could map the limit exactly: post a payload with one field missing, repeatedly, and watch for the flip from 400 to 200. The concealment held for well-formed payloads and evaporated for malformed ones, which are free to generate.

Fixing the ordering closed both problems at once. Once validation runs first, every payload that reaches the limiter is well-formed, so throttled and successful responses really are identical in status, body and headers for everything that gets that far. Not in timing: a throttled request skips the store write and the email call, so it answers faster.

The order, and the reason for each position

parse  →  honeypot (counts, answers like success)  →  validate (400, costs nothing)  →  limit  →  process

Honeypot first, and it costs a unit. A hidden field filled in means a bot. Charging it means an address that trips the honeypot also spends the allowance its later, clean-looking submissions would use, so a bot that mixes payloads is throttled sooner. It does not stop the honeypot requests themselves; those are answered like success either way. The cost of this choice, and it is a real one: a bot can spend a shared address's allowance, so a person behind the same NAT pays for it. We took that trade knowingly and wrote a test that states it, rather than discovering it later.

Validation second, and it costs nothing. A payload that fails the schema was never a submission. Charging for it means a user's own errors deny their next correct attempt.

The limit third. Now it only counts real submissions.

Two smaller things in the same area

A blank part is a typo, not a zero. Number("") is 0 in JavaScript (MDN, Number), so a configuration value of "5," — a trailing comma — would have parsed as "five a minute, none a day" and closed the route, with every response still looking like success. Review caught it before it shipped. Treat a blank part as invalid and fall back to the default instead.

A deliberate closure should say so. Concealing a throttle is worth something, because a caller could otherwise map the limit. Concealing a closure protects nothing — everyone is refused — and it leaves the operator who closed the route unable to tell it apart from an open one with their own smoke test. Our closed state answers 503, not a success shape.

What to check in yours

Three questions, and the first is the one that finds this bug:

1. Does a request that fails validation consume a unit? Post five invalid payloads, then one valid one, and see whether the valid one lands.
2. Does a throttled response differ from a successful one in status, body or headers — and does that difference change with the payload's validity?
3. Where does the address come from? Ours is the first x-forwarded-for element, which is trustworthy on Vercel because Vercel overwrites that header (Vercel, request headers), and is client-controlled almost everywhere else (MDN, X-Forwarded-For). That assumption belongs in your documentation, not in your head.

The short version

• PostgREST maps a JSON key to a column of the same spelling. receivedAt needs a column created as "receivedAt", with the quotes. Unquoted, Postgres folds it to receivedat and every insert fails with PGRST204.
• Legacy service_role keys are JWTs and go in both apikey and Authorization: Bearer. The newer sb_secret_… keys are opaque, not JWTs, and belong in apikey alone.
• Both failures happen on Supabase's side of the request, not in your code. If your write helper swallows errors — a reasonable thing for it to do — your application reports success and loses the row.

Trap 1: PostgREST does not convert your casing

Post a body to /rest/v1/<table> and PostgREST takes each JSON key as a column name verbatim (PostgREST, error reference). There is no camelCase-to-snake_case translation step. So this payload:

{ "email": "a@example.com", "receivedAt": "2026-09-11T22:20:02.865Z" }

needs a column literally named receivedAt. Postgres folds unquoted identifiers to lower case (PostgreSQL, identifiers), so the obvious DDL creates the wrong thing:

-- Creates "receivedat". Every insert above now fails.
create table public.leads (receivedAt timestamptz);

-- Creates "receivedAt". Correct.
create table public.leads ("receivedAt" timestamptz);

The error is specific once you see it:

PGRST204  Could not find the 'receivedAt' column of 'leads' in the schema cache

Two ways out, and the choice is worth making deliberately. Quote the identifier and keep the casing your application already sends, which is what we did — it keeps the write path free of a mapping layer, at the cost of a column you must always quote in SQL. Or use snake_case columns and translate in the client, which is tidier in the database and adds a place where a field can be forgotten.

Either is fine. Choosing neither, and discovering the mismatch from production inserts, is the expensive option.

Trap 2: the new keys are not JWTs

Supabase's legacy anon and service_role keys are HS256 JWTs, so either one works in Authorization: Bearer, including the usual shape of sending the same key in both apikey and Authorization: Bearer.

The newer keys do not have that shape. sb_secret_… and sb_publishable_… are opaque strings. Supabase allows one in Authorization: Bearer only when it exactly matches the apikey header, as a backward-compatibility allowance (Supabase, discussion #29260), and anything that verifies that header as a JWT fails on it (Supabase, API keys).

A helper that sends the same key in both headers keeps working on the REST API after rotation. What breaks is anything that puts a new-format key in Authorization: Bearer next to a different apikey value, or hands that header to code that expects a JWT. Send new-format keys on apikey alone, as Supabase recommends:

export function authHeaders(key: string): Record<string, string> {
  const opaque = key.startsWith("sb_");
  return opaque
    ? { apikey: key }
    : { apikey: key, Authorization: `Bearer ${key}` };
}

Two things worth saying about that function. It decides transport, never privilege — a publishable key takes the same path and runs as the anon role, so your RLS policies decide what it can do. And it keeps the code on the header shape Supabase documents before the legacy keys are retired, which Supabase currently plans for late 2026.

Why both of these are quiet

A write helper that never throws is good design. A capture failure should not take down a request that had other work to do. But "never throws" and "never reports" are different, and it is easy to ship the first while accidentally shipping the second:

const stored = await recordLead(lead);   // null on success, a code on failure
if (stored !== null && stored !== "NOT_CONFIGURED") {
  console.error("[contact] lead store failed", { stored });
}

Without that check, whenever the rest of the request succeeds, a store refusal returns the same 200 as a healthy write, and nothing records why the row is missing.

How to verify, in about a minute

Do not trust your own success path. Go to the data.

-- Every column, with its real spelling.
select column_name, data_type
from information_schema.columns
where table_schema = 'public' and table_name = 'leads';

Then write one row through the real endpoint and select it back. On our lead store this check confirmed both: the quoted receivedAt column accepted the value, and a publishable key sent with apikey alone reached PostgREST and was refused by RLS — [] on select, 42501 on insert. That second result is the one worth copying. It proves the key format reaches the database and that the table is closed to anything but the server's own key.

That does not make software automatic. It changes where skilled people spend their time.

Implementation is faster; understanding is still the work

Modern tools can accelerate routine code, integrations, tests, and documentation. They cannot decide which workflow matters most, why it is failing, what people will trust, or which tradeoff is right for the business.

Those questions require direct observation, judgment, and responsibility. The useful shift is that experienced builders can spend more of the engagement on them instead of paying a large coordination tax.

The product is the working system

Code is only one part of a business system. A complete implementation connects:

• the people responsible for the work;
• the information they need;
• the decisions and approvals they make;
• the software and integrations already in use;
• the exceptions that cannot be automated safely; and
• the operating plan after launch.

A faster coding process is valuable only when all of those pieces still work together.

What a client should expect

Smaller delivery teams should increase clarity, not lower the standard. A serious engagement still needs:

1. A clear problem definition. The team can explain the root cause in business language, not only repeat the requested feature.
2. A complete workflow. The implementation covers normal work, exceptions, permissions, and recovery.
3. Visible acceptance checks. The client can see what success means and whether the system meets it.
4. A responsible launch. Ownership, monitoring, support, and change are defined before the system becomes daily infrastructure.
5. A human commercial decision. Scope, price, and commitments are reviewed and approved by people.

AI may support the work behind the scenes. It is not the service the client is buying.

Where the model works best

The strongest fit is an important workflow that is too specific for off-the-shelf software and too costly to leave manual. The business understands the pain but may not know what the right system should look like.

Examples include exception routing, multi-step approvals, client onboarding, field operations, document-heavy reviews, and work split across several disconnected tools.

The starting point is not a technology selection. It is one recurring problem with a measurable business consequence.

Fewer handoffs, clearer responsibility

When the same expert team understands the workflow, designs the system, implements it, and stays through launch, less meaning is lost between disciplines. Questions reach the people who can change the system. Decisions stay connected to the original problem.

That is the durable advantage of a small team: not simply lower cost or faster code, but a shorter path from business reality to a system that works.

LOJIK uses a focused delivery loop: understand one workflow, build the smallest complete version of the fix, test the normal path and the failure paths, then expand from evidence. The client sees progress in working software—not in a growing pile of project documents.

Start with the work, not the feature request

A request such as “add an approval dashboard” sounds specific, but it may describe only the visible symptom. The real problem could be missing information at intake, unclear decision rights, or exceptions that have nowhere to go.

Before implementation, we trace:

• what should happen;
• what happens instead;
• who touches the work;
• which tools and handoffs are involved;
• where time, errors, or uncertainty enter the process; and
• what result would prove the workflow improved.

That produces a system plan tied to the business problem. It also prevents a polished interface from being built around the wrong process.

Build a complete slice

Large projects often look busy for months before anyone can use them. We prefer complete slices: one real input travels through the workflow, reaches the correct decision, records what happened, and ends in a useful result.

A complete slice may be narrow, but it includes the parts that make the workflow trustworthy—permissions, exceptions, notifications, audit history, and recovery. Each slice becomes a working foundation for the next one.

Test the paths people usually discover too late

The happy path is rarely where business systems fail. We test the conditions that create emergency spreadsheets and manual workarounds:

• required information is missing;
• an integration is unavailable;
• the same request arrives twice;
• an approval takes too long;
• a person lacks permission;
• a file is unsafe or unsupported; and
• a change needs to be reversed.

The goal is not to claim that failure is impossible. The goal is to make failure visible, contained, and recoverable.

Make progress easy to evaluate

Clients should not need to interpret engineering activity to know whether the system is getting better. Reviews center on concrete questions: Does the workflow now handle the agreed scenario? Can the right person see and act on the exception? Is the result recorded? What remains unresolved?

If a result falls short, it returns to implementation with a clear correction. Approval comes from working behavior against agreed expectations.

Launch includes what happens next

A system is not finished when it reaches production. It needs an owner, monitoring, support, current documentation, and a safe way to change.

The client can run the finished system with a structured handoff, ask LOJIK to manage it, or transition responsibility over time. That operating choice is designed before launch so the business is not left with software nobody is prepared to own.

Moving quickly is the result of focus and clear feedback. Reliability comes from following the workflow all the way through.

It is tempting to call this a chatbot problem. It is really an end-to-end workflow problem.

The result the clinic needs

The useful outcome is not an automated reply. It is a confirmed appointment that appears in the clinic’s calendar with the right patient details, instructions, and follow-up.

The system has to understand the request, find a valid opening, collect only the information the clinic needs, confirm the appointment, send a reminder, and give staff a clear way to intervene.

If any one of those steps is missing, the receptionist still has to reconstruct the conversation by hand.

Design around the channel patients already use

WhatsApp is familiar, asynchronous, and already part of daily life for many patients and clinics. A successful system should preserve that ease while adding structure behind the conversation.

The patient can write naturally in Spanish. The system identifies the request, asks focused follow-up questions, and shows available times. Confirmed appointments sync to the calendar the clinic already uses, so staff do not have to manage a second schedule.

Exceptions define whether the system is trustworthy

Healthcare conversations do not stay on the happy path. The workflow needs explicit routes for situations such as:

• symptoms that may require urgent human attention;
• a patient asking a medical question the system should not answer;
• a requested doctor or service that is unavailable;
• duplicate or conflicting appointments;
• a minor or caregiver booking for someone else;
• a change or cancellation near the appointment time; and
• a message that cannot be understood confidently.

In those cases, the system should pause, explain what happens next, and alert the correct person. Automation handles the repeatable work; clinic staff keep authority over clinical and exceptional decisions.

Local context is part of the implementation

The language has to sound natural for the clinic and its patients. Hours, holidays, payment instructions, forms of address, and escalation expectations vary by location and practice.

That context cannot be added as a decorative translation layer. It shapes the questions, the handoff to staff, the reminder schedule, and the information shown before a patient confirms.

Privacy belongs inside the workflow

The system should collect the minimum information needed for scheduling, explain how that information is used, limit who can access it, and define retention and deletion behavior. Medical advice and sensitive clinical intake should remain outside the scheduling flow unless the clinic has deliberately designed and approved a compliant process for them.

Measure the business result

Useful measures include response time, completed bookings, staff interventions, no-shows, duplicate appointments, and requests that could not be resolved. Those signals show where the workflow is helping and where it still needs human attention or a better rule.

The opportunity is larger than a conversational interface. It is a reliable front desk that follows the appointment from first message to completed visit while keeping the clinic in control.

The best interface work makes a complex offer easier to understand. It does not ask the visitor to decode the design.

The first screen has four jobs

Before a visitor scrolls, the page should answer:

1. What does this company provide?
2. What problem does it solve?
3. Who is it for?
4. What happens when I take the next step?

If the hero cannot answer those questions, another animation will not rescue it. The visual system should reinforce the message—for example, showing scattered work becoming one connected workflow—not compete with it.

Motion needs a specific purpose

Useful motion can show sequence, causality, progress, or a change in state. It can help a visitor understand how inputs move through a system or how disconnected steps become one flow.

Motion becomes decoration when it repeats the same idea, delays access to content, or exists mainly to demonstrate production value. A good test is simple: if the animation disappears, does the explanation become less clear? If not, the page may be stronger without it.

Premium does not mean dense

High-end interfaces often feel calm because each section carries one idea. Strong typography, intentional spacing, a controlled palette, and a small number of distinctive details create more confidence than a screen full of competing effects.

This is especially important for a service that already requires explanation. The visual design should reduce the effort needed to understand the offer.

Performance is part of the impression

A cinematic asset that arrives late or stutters on mobile signals the opposite of technical confidence. Every visual should have a performance budget, a responsive composition, and a reduced-motion alternative.

Practical checks include:

• useful content appears before large media finishes loading;
• the main action remains stable while assets load;
• mobile layouts do not crop the explanation;
• animation avoids blocking scroll or input;
• reduced-motion users receive an equally complete experience; and
• the page remains clear when viewed on a slower connection.

Every action should say what it does

Generic buttons such as “Explore,” “Continue,” or “Get started” force the visitor to guess. A stronger action names the value or destination: “Find what to fix first,” “See how the system works,” or “Start my business review.”

The primary and secondary actions should also be meaningfully different. One begins the product experience. The other teaches, shows an example, or explains delivery.

Conversion is a comprehension test

The page succeeds when the right visitor can explain the offer in one sentence, recognize their own problem, and predict the next step. That is the standard the visual system serves.

Beautiful design creates desire. Clear product language turns that desire into a confident action.