# Add StatusPages Error Handling to a Ktor API

Yes. An agent installs Ktor's StatusPages plugin, maps your service exceptions to JSON error responses, removes the per-route try/catch, tests it and opens a PR.

[Run this on Rush](https://cloud.getrush.ai/run/add-api-error-handling/ktor/). Opens the console with this prompt ready to send, in a Project that has your repository.

## What the agent does

The agent reads the routes before it touches them, because error handling is only right if it knows what each one throws. In a service laid out like the `postgres` sample in ktorio/ktor-samples, `build.gradle.kts` applies the Ktor plugin 3.6.1 on Kotlin 2.4.20 with content negotiation, kotlinx JSON, Netty, logback, the YAML config module and the PostgreSQL driver, lists `ktor-server-test-host-jvm` and `kotlin-test-junit` as test dependencies, and has no `src/test` directory. `PostgresApplication.kt` installs serialization and routing, and `connectToPostgres` reads the user, password and database from `postgres.yaml`, the same file `docker-compose.yaml` extends to start the database.

`plugins/Routing.kt` wraps each of the four `/articles` routes in its own `try`: `DbElementInsertException` on create answers an empty 500, `DbElementNotFoundException` on read answers an empty 404, and an `IllegalArgumentException` from a missing or non-numeric id answers an empty 400 on read, update and delete. Two things fall through. `ArticleService.update` and `delete` return the row count from `executeUpdate` and never throw, so a `PUT` or `DELETE` for an id that does not exist answers 200. And both custom exceptions extend `Throwable` rather than `Exception`, so any handler written for `Exception` would miss them, which the agent notes before writing one.

The change adds `ktor-server-status-pages-jvm` to the dependencies and a `plugins/StatusPages.kt` with `configureStatusPages()`, called from the application module: `exception<DbElementNotFoundException>` answers 404, `DbElementInsertException` 500, `IllegalArgumentException` 400, Ktor's `BadRequestException` 400 for a body `call.receive<Article>()` cannot parse, and a last `Throwable` handler that logs through `call.application.log` and answers 500 with a generic message so no stack trace reaches a client; a `status(HttpStatusCode.NotFound)` block gives an unknown path a body too. Every answer is a serializable `ErrorResponse(code, message)` in `models/`, sent through the content negotiation already installed. `Routing.kt` loses its `try` blocks, and update and delete throw `DbElementNotFoundException` when the service reports zero rows.

The sandbox has no Docker, so the agent installs PostgreSQL from apt, starts it, and creates the `articles` database with the user and password from `postgres.yaml`, then runs the service with `./gradlew run` and sends the failing requests with curl: a missing id, a non-numeric id, malformed JSON, an update of an id that does not exist, and an unknown path, reading each status and body. It also writes `src/test/kotlin/com/example/StatusPagesTest.kt` on `testApplication`, installing the plugin with a route that throws each exception, so the mapping is checked without a database, and runs `./gradlew test`, the task `build-all.sh` runs for every sample in CI.

## Start it with one API call

`POST https://api.phoenix.so/o/{org}/sessions`

```json
{
  "agent": "claude",
  "input": "Add StatusPages error handling to this Ktor service. Read build.gradle.kts, every file under src/main, postgres.yaml and docker-compose.yaml first. Add the ktor-server-status-pages dependency and a plugins/StatusPages.kt that maps DbElementNotFoundException to 404, DbElementInsertException to 500, IllegalArgumentException and Ktor's BadRequestException to 400, and any other Throwable to a logged 500 with a generic message, each answered as a serializable ErrorResponse with a code and a message through the installed content negotiation, plus a body for an unmatched route. Remove the try blocks from Routing.kt, and make update and delete answer 404 when the service reports zero rows. Note that the custom exceptions extend Throwable, not Exception. In the sandbox, install PostgreSQL from apt, create the database, user and password postgres.yaml names, run the service and send the failing requests with curl; also write a testApplication test that covers each mapping without a database and run ./gradlew test. Open a pull request whose description quotes the curl transcript and the test output and names the responses that changed.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app"
    }
  ]
}
```

1. **Get an API key.** In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
2. **Send the request.** POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
3. **Read what came back.** Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.

## What comes back

What comes back is a pull request that changes `build.gradle.kts`, `PostgresApplication.kt` and `Routing.kt`, adds `plugins/StatusPages.kt`, `models/ErrorResponse.kt` and the test file, and leaves `ArticleService.kt`, the config and the Compose files alone. The description quotes the curl transcript with each status and JSON body, the `./gradlew test` output, and a short list of responses that changed: 404 and 500 now carry a body, malformed JSON answers 400, and an update or delete of a missing id answers 404 where it answered 200.

The run's record keeps the PostgreSQL install and the `./gradlew run` log, every request the agent sent with its answer, and the test run, so a reviewer can see the behaviour against a real server before checking out the branch.

Before merging, a reviewer decides whether any client depends on the old 200 from `PUT` and `DELETE` on a missing id, reads the generic message the `Throwable` handler returns, and checks that the log line carries the exception the client no longer sees.

## Run it on every Linear issue labelled `agent`

A team that tracks API cleanup in Linear starts the work from the issue. An automation with a `linear` trigger on `linear.issue.labeled` and `agent` in `config.labels` starts a run for each issue that gains the label; the trigger adds the issue after the automation's prompt, which asks the agent to read the issue, make the change it describes in the named service, and open a pull request that links back to the issue, so the prompt itself names no service and no exception.

Each run reads the issue it was given and the repository the Project holds, installs what the service needs in its own sandbox, and leaves a pull request with its own transcript in the record. An issue that asks for a different mapping, say a 409 on a duplicate insert, gets that mapping, because the run reads the issue rather than a template.

## Why run it on Rush?

Error handling written without running the service gets the edges wrong: a handler on `Exception` that never sees an exception extending `Throwable`, a malformed body that still answers 500, or a route that quietly answers 200 for a row that was never there. In a Rush sandbox the agent installs the real database, runs the real server and sends the real bad requests, and reads each answer before it writes the mapping.

The curl transcript and the test run stay with the pull request, so the reviewer reads what the API answers rather than what the diff suggests. The same job across a team's services runs in parallel, each with its own machine, its own database and its own pull request.

## Frequently asked questions

### Why does it matter that the exceptions extend Throwable?

Because a StatusPages handler is matched by type. `exception<Exception>` would never see `DbElementNotFoundException` or `DbElementInsertException`, which extend `Throwable` directly, and they would reach the catch-all instead. The agent registers each class explicitly and keeps a `Throwable` handler last.

### Does this change what existing clients see?

Yes, in three places the pull request names: 404 and 500 answers gain a JSON body, a body the server cannot parse answers 400 instead of whatever the default pipeline produced, and `PUT` or `DELETE` on a missing id answers 404 rather than 200. A client that reads only the status is unaffected by the first; the reviewer decides on the third.

### Can it run the service without Docker?

Yes. The sample starts PostgreSQL with Docker Compose, but the sandbox has no Docker, so the agent installs PostgreSQL from apt and creates the database, user and password `postgres.yaml` names. The service connects to `localhost:5432` either way.

### Will stack traces leak to clients?

No. The last handler logs the throwable through the application logger and answers a fixed message, so the detail goes to the server log, which `logback.xml` already configures, and the client gets a status and a code.

### Is there a test that does not need the database?

Yes. The `testApplication` test installs the plugin with a route per exception and asserts the status and body for each, using the test host dependency the build already declares, so `./gradlew test` checks the mapping on any machine.

## More Ktor jobs

- [Add HTTP Caching to a Ktor API](https://getrush.ai/run/add-caching/ktor/)
- [Add Response Compression to a Ktor API](https://getrush.ai/run/add-compression/ktor/)
- [Add Connection Pooling to a Ktor Server with HikariCP](https://getrush.ai/run/add-connection-pooling/ktor/)

## The same job on other stacks

- [Add API Error Handling to an Express and Sequelize App](https://getrush.ai/run/add-api-error-handling/sequelize/)
- [Add LLM API Error Handling to a Streamlit App](https://getrush.ai/run/add-api-error-handling/streamlit/)
- [Add Global Error Handling to TanStack Query](https://getrush.ai/run/add-api-error-handling/tanstack-query/)

## Keep reading

- [How a Rush run works on your repository, from request to pull request](https://getrush.ai/cloud/)
- [Compare cloud agents, agent sandboxes and AI code review](https://getrush.ai/compare/)
- [Rush pricing: Free, Pro and Max](https://getrush.ai/pricing/)
