Errors and status codes

Every Aide endpoint shares one error handler:

export function toAuthError(err: unknown): NextResponse {
  if (err instanceof UnauthorizedError) {
    return NextResponse.json({ error: err.message }, { status: 401 });
  }
  const message = err instanceof Error ? err.message : "Internal error";
  return NextResponse.json({ error: message }, { status: 500 });
}

So failures are always JSON with a single error key:

{ "error": "Unauthorized" }

Only UnauthorizedError produces a 4xx. Anything else that throws — a database timeout, a bug, a bad body that reaches a query — comes back as 500 with the raw exception message in error.

Do not display error to end users verbatim. On a 500 it is an internal message that may leak schema detail. Log it, show something generic.

Status codes

There is no 403 on these routes, and no 422. A record you are not entitled to read returns 404, not 403 — see Businesses, staff and permissions.

400 validation messages

Validation is hand-written and per-route. These are the exact strings:

Note the naming: validation failures say what is required, not what you sent wrong. There is no field-level detail, so a 400 tells you the rule but not the offending value.

POST /api/auth/register is the one endpoint with a 409, because it checks for a duplicate email before the transaction. See Authentication.

401 and its two messages

UnauthorizedError carries a default message of Unauthorized, but one route raises it with something more specific:

if (businessIds.length === 0) {
  throw new UnauthorizedError("No business membership");
}

Both are 401. The distinction matters for UX: a No business membership user is signed in correctly and needs an onboarding flow, not a re-login. That is the state a user lands in if the business record was removed from under them.

How credentials are resolved

const token = bearerToken(request);
if (token) {
  try { return fromClaims(await verifyToken(token)); }
  catch { return null; }        // bad token → 401, session not consulted
}
const session = await getServerSession(authOptions);

The order is bearer token first. If an Authorization: Bearer header is present and fails verification, the session cookie is not tried as a fallback — the request is rejected. A stale token on a device that also has a valid cookie still gets 401. Send no header, or a current one.

Three routes bypass this entirely and use getServerSession directly, so they accept session cookies only — a bearer token will not work on them:

• GET /api/business
• GET /api/admin/stats
• GET /api/reviews, and /api/reviews/{id}

This is worth knowing before you write a mobile client that assumes bearer auth works everywhere.

404 responses

404 means "no such record scoped to your business", never "this record belongs to someone else". Both are the same response:

The releases pair is an abuse guard rather than a not-found: when GitHub fails or returns non-OK, the proxy returns 404 with an empty body rather than surfacing the upstream failure. A 404 there means "no builds are published", and the response is cacheable for five minutes.

Soft deletes and 0 counts

Mutations that report a count can succeed with a zero:

{ "updated": 0 }
{ "deleted": 0 }

That means the id did not match a live row belonging to you. It is a 200, not a 404. Do not treat 0 as an error — it is the normal result of an idempotent retry, and for another user's notification it is the only signal you get.

What a client should do

Never retry a 500 in a tight loop. The common cause is a malformed body that reached a database query, and retrying it will fail identically every time.

Related

• Authentication
• API introduction
• Businesses, staff and permissions
• Sync — the endpoint with the most conditional behaviour