Skip to content

Error handling

This page explains what happens when something fails: what the API answers, what is left in the database, what the user sees and what the worker does. It is part of section 9 of the arc42 template.

A failure has three audiences. The user needs a sentence in their language that says what to do. The front end needs something stable to decide on, which a sentence is not. The person who investigates needs the cause, which must never reach the user when it contains data. One error text cannot serve the three.

  • The API has one error body for every failure, from 400 to 503. Clients decide on its code, never on its text.
  • A code is stable. A code is never renamed; a new case gets a new code.
  • A failed request leaves nothing behind: its transaction is rolled back, including the audit row.
  • A server error (5xx) answers with a generic message. The cause goes to the log, with sensitive fields removed, next to the request id that the answer carries.
  • Background work that fails is retried a fixed number of times and then recorded as failed. It is never dropped in silence.

Every error answer has this shape (apps/api/src/core/errors/error.schema.ts). The values below are an example.

{
"code": "validation_failed",
"message": "Some fields are invalid.",
"status": 400,
"requestId": "0c5e7d4e-6c1f-4f5e-9d53-5a1c2f0e8a11",
"issues": [{ "path": "email", "code": "invalid_format", "message": "Invalid email address" }]
}
Field Meaning
code One of the codes of the catalog, in English snake case. The value a client switches on and translates.
message An English sentence for logs and developers. Screens do not show it.
status The HTTP status, repeated in the body.
requestId The id of the request, also in the X-Request-Id header. The log line of a server error carries the same id.
issues Optional. One entry per field that failed validation, with the dot path of the field. A duplicate issue may name the record that already holds the value, so the screen can link to it.

The catalog is one file, apps/api/src/core/errors/error-codes.ts. It has 84 codes today:

Status Codes Used for
400 8 A malformed or invalid request: validation_failed, invalid_reference.
401 2 No session, or wrong credentials.
403 10 Signed in but not allowed: forbidden, module_disabled, cross_site_request.
404 4 Not found. A record of another company is not found too: under row level security it does not exist for the session.
409 53 The request is valid but the state does not allow it: record_archived, slot_taken, duplicate_value, write_conflict, tenant_changed.
410 2 An invitation that expired or was revoked.
413, 415, 429 1 each Body too large, wrong media type, request limit reached (with Retry-After).
500 1 internal_error: anything unexpected.
503 1 service_unavailable: a dependency is down, or the health check failed.

Most codes are 409 by design: a business rule that refuses an action has its own code, so the screen can say exactly why and offer the next step.

The paths in this table are under apps/api/src/core, except where another folder is named.

Part What it does
One error type Services and guards throw ApiError with a code of the catalog. The status and the default message come from the catalog. In errors/api-error.ts.
One filter ApiErrorFilter catches everything that is thrown and writes the body. Anything that is not an ApiError becomes internal_error, except the cases below. In errors/error.filter.ts.
Validation A request that fails its schema answers validation_failed with one issue per field, before the handler runs. In http/validation.ts.
Database errors with a meaning In a register, a unique violation answers 409 duplicate_value and a foreign key violation answers 400 invalid_reference, each with the field in issues. In registers/write.ts.
Concurrent writes A deadlock or a serialization failure answers 409 write_conflict. PostgreSQL already rolled the transaction back, and the same request sent again succeeds. The API does not retry by itself: only the client knows whether sending again is safe.
One transaction per request Every authenticated handler runs in one transaction. An error rolls it back whole. A write that recorded no audit row is treated as an error and rolled back too. Jobs queued for after the commit run only if the commit happened. In http/transaction.interceptor.ts.
A lost connection When PostgreSQL ends a connection in use, only the request that was using it fails. The process stays up and the next request is served. In createDb of packages/db.
A failure after the first byte A streamed answer, such as a CSV export, that fails after its headers were sent cannot become JSON. The API cuts the connection, so the client sees a broken download and not a complete file.
Missing configuration Without the encryption key, the routes that write or reveal sensitive data answer 503 service_unavailable and write nothing. Saving a calendar OAuth application in the platform panel answers 409 secrets_key_missing. With a real provider selected and a setting missing, the API and the worker refuse to start and name the variable. In sensitive and config/config.ts.
  • On a 5xx, the body carries the message of the catalog, never the message of the exception.
  • Before an exception is logged, any field named as a sensitive column is replaced with [redacted] (apps/api/src/core/sensitive/redact.ts). The same replacement runs on the fields a route adds to an error body.
  • A route whose address contains a token is logged with [token] in its place.

See Sensitive data.

Part What it does
One helper request awaits a call of the generated client and returns the data, or throws ApiRequestError with the code, the status and the issues. A request that never reached the server becomes network_error; an answer that is not the error body becomes unknown_error. In packages/app-kit/src/request.ts.
Translation The screen shows errors.<code> from its dictionary, in the language of the user. In apps/web/src/i18n.
Field errors The issues of a validation_failed answer are placed on the fields of the form by their path. In apps/web/src/lib/forms.ts.
Session changes A 401 anywhere clears the session and sends the user to Sign in. tenant_changed tells the tab that another tab switched company. A 403 that means the company or a module changed reloads the session. In apps/web/src/api/query-client.ts.
Retries A read that failed is retried twice, except on a 4xx, which does not get better by retrying. In the same file.
Public pages The careers server turns an API failure into a page: a company or job that is not public is a 404 page, and an API that is down or over its request limit is a 503 or 429 page with the same Retry-After. In apps/careers/src/lib/api.ts.
Work On failure
Delivery of a domain event to a consumer The consumer’s transaction is rolled back and the delivery is tried again with a growing wait, 8 attempts in all. After the last one, a row in domain_event_failures records the event, the consumer, the attempts and the last error. In apps/api/src/core/events.
Sending a message A temporary failure of the provider leaves the message queued and waits 30 seconds, 2 minutes, 10 minutes and 30 minutes. The fifth failure ends the message as failed, with the reason. An SMS provider that does not answer in time ends the message as failed at once: the provider may have accepted it, and a second attempt could deliver the same text twice. In send-queue.runner.ts of apps/api/src/modules/platform-messaging.
A message refused by a rule Not an error. A message refused for lack of consent, an opt-out or the daily cap is stored with its reason and is never sent later. See Messaging.
A pass over many companies Each company is processed on its own. In the sending pass, a failure in one company is logged and the pass goes on to the next. See Background work.
Guarantee Enforced by
Validation, unknown routes, malformed JSON and server errors all answer with the same body. apps/api/test/errors-audit.test.ts
Every operation of the contract documents the error body. apps/api/test/openapi.test.ts
A failed write leaves neither data nor an audit row. apps/api/test/errors-audit.test.ts
A sensitive value is in neither the answer nor the log of an unexpected error. apps/api/test/sensitive.test.ts
A token in an address is not logged. apps/api/test/error-filter-log.test.ts
A stream that fails cuts the connection. apps/api/test/error-filter-stream.test.ts
A connection ended by the database fails one request and not the process. apps/api/test/connection-loss.test.ts
Database errors of a register name the field. apps/api/test/register-pattern.test.ts
A failed delivery is retried and then recorded. apps/api/test/domain-events.test.ts
The front end helper maps every kind of failure to a code. packages/app-kit/test/request.test.ts
Every code has a text on screen. apps/web/test/i18n.test.ts
  • Logs are the output of each process. There is no error tracking service, no alerting and no dashboard of failures in the repository. They are part of the production environment, which is Proposed. See the Deployment view.
  • Failed deliveries are recorded, not surfaced. domain_event_failures has no screen. Reading it is a database task today.
  • write_conflict asks the user to try again. The office system shows the sentence of the code and does not send the request again by itself.
  • Some validation messages are in English only. See Internationalization.