# When the Database Says No: Bad ids, Duplicates and Not Found

An API answers each way a request can fail with the status that says whose problem it is, so a text that isn't an ObjectId gets 400, an id with no pet 404, a duplicate key (code 11000) 409, a document the validator refuses (code 121) 400, and a database that's down 500 with the details logged and never sent.

Journeyman · MongoDB · Node.js · Updated November 19, 2026

By Gregor Dzierzon

## After this lesson you can

- Choose the status code for a bad id, a missing document, a duplicate key, a refused document and a database that's down
- Turn MongoDB's error codes 11000 and 121 into 409 and 400 in an error handler, and log a 500's details without sending them to the caller

## Key takeaways

- The status code tells the caller whose problem it is. A 4xx means the request needs fixing, and a 5xx means the server failed.
- new ObjectId stops with a BSONError on text that isn't an id, so the API checks first with ObjectId.isValid and answers 400.
- A well-formed id with no pet is a 404, which the route answers when the data layer gives back null.
- A failed write carries MongoDB's error code. 11000 is a duplicate key, answered with 409 Conflict, and 121 is a document the validator refused, answered with 400.
- Anything else, such as MongoDB being down, is a 500. The details go to the terminal for you, and the caller gets one calm sentence.

Someone types an address by hand and gets a digit wrong. Two volunteers add the same new dog at the same moment. The database restarts in the middle of the afternoon. Every API meets these, and what it answers decides whether the person on the other end can fix the problem or is left guessing. You'll write this handling for every API you put on a database.

The examples use the pet API from *A Data Layer: One File That Talks to the Database*.

## A 500 for someone else's typo

The warm-up API's ids were `"1"` to `"6"`, and someone still has a bookmark for `/pets/2`. Ask the API from the last lesson for it:

```text
GET /pets/2
HTTP/1.1 500 Internal Server Error
{"status":500,"title":"Internal Server Error","detail":"Something went wrong on our side."}
```

The terminal shows why: `BSONError: input must be a 24 character hex string, 12 byte Uint8Array, or an integer`. `new ObjectId("2")` refused the text, the error reached the error handler, and the API told the caller it was the server's fault. It wasn't: the request was wrong, and nothing on the server is broken.

A **status code** is the first thing a caller reads, and it says whose problem it is. Codes in the 400s mean "your request needs fixing"; codes in the 500s mean "we failed, try again later". Here is each way a pet request can fail, and its answer:

| What happened | Whose problem | Status |
|---|---|---|
| The id isn't an ObjectId at all, such as `2` | The caller's | 400 Bad Request |
| The id looks right, but no pet has it | Nobody's: it isn't there | 404 Not Found |
| Another pet already has that name (code 11000) | The caller's: it clashes | 409 Conflict |
| The validator refuses the pet (code 121) | The caller's | 400 Bad Request |
| MongoDB is down | The server's | 500 Internal Server Error |

## A bad id: check before you ask

The driver can tell you whether text could be an ObjectId, without asking the database: `ObjectId.isValid(id)`. So the data layer gets one more small function, and the routes still never touch the driver:

```javascript
export function isPetId(id) {
  return ObjectId.isValid(id);
}
```

Each route with an `:id` checks it first, before it asks the data layer for the pet. `!` is read "not":

```javascript
if (!isPetId(req.params.id)) {
  sendProblem(res, 400, `${req.params.id} isn't a pet id.`);
  return;
}
```

The missing pet already had its answer: `getPet` gives back `null`, and the route answers 404. Now the two are told apart:

```text
GET /pets/2
HTTP/1.1 400 Bad Request
{"status":400,"title":"Bad Request","detail":"2 isn't a pet id."}

GET /pets/6740c0000000000000000099
HTTP/1.1 404 Not Found
{"status":404,"title":"Not Found","detail":"There's no pet 6740c0000000000000000099."}
```

## Duplicates and refused pets: the error's code

The center gives every pet a name no other pet in the shelter has, so the staff never mix up two dogs called Biscuit. A unique index makes MongoDB keep that rule, as in *Unique and Text Indexes*, and a validator from *Schema Validation with $jsonSchema* takes only dogs, cats and rabbits, with a name, a species and a whole-number age:

```mongodb
db.pets.createIndex({ name: 1 }, { unique: true })
db.runCommand({
  collMod: "pets",
  validator: {
    $jsonSchema: {
      required: ["name", "species", "age"],
      properties: {
        name: { bsonType: "string" },
        species: { enum: ["dog", "cat", "rabbit"] },
        age: { bsonType: "int", minimum: 0 }
      }
    }
  }
})
```

```text
name_1
{ ok: 1 }
```

When MongoDB refuses a write, the driver's error is a `MongoServerError`, and its `code` is MongoDB's number for the reason. This script tries a second Biscuit and a hamster:

```javascript
import { MongoClient } from "mongodb";

const client = new MongoClient(process.env.MONGODB_URI);
await client.connect();
const pets = client.db("maple_street").collection("pets");

for (const pet of [
  { name: "Biscuit", species: "dog", age: 5 },
  { name: "Peanut", species: "hamster", age: 1 },
]) {
  try {
    await pets.insertOne(pet);
  } catch (error) {
    console.log(`${pet.name}: ${error.name}, code ${error.code}`);
  }
}

await client.close();
```

```text
Biscuit: MongoServerError, code 11000
Peanut: MongoServerError, code 121
```

**11000** is a **duplicate key error**: a second document with a value a unique index allows only once. **121** means the validator refused the document. Both are the caller's to fix, so neither should be a 500.

The routes don't need a `try` and `catch` for these. In Express 5, when an `async` route's `await` fails, the error goes to the **error-handling middleware**, the function with four parameters at the end of `app.js`. It reads the code and picks the answer:

```javascript
app.use((err, req, res, next) => {
  if (err.code === 11000) {
    sendProblem(res, 409, "Another pet already has that name.");
    return;
  }
  if (err.code === 121) {
    sendProblem(res, 400, "That pet breaks the center's rules: check its name, species and age.");
    return;
  }
  console.error(err);
  sendProblem(res, 500, "Something went wrong on our side.");
});
```

```text
POST /pets
HTTP/1.1 409 Conflict
{"status":409,"title":"Conflict","detail":"Another pet already has that name."}

POST /pets
HTTP/1.1 400 Bad Request
{"status":400,"title":"Bad Request","detail":"That pet breaks the center's rules: check its name, species and age."}
```

## The database is down: a 500 and a log line

Everything else falls through to the last two lines. Stop MongoDB while the API runs and ask for `/pets`, and `find` fails with a `MongoNetworkError`:

```text
GET /pets
HTTP/1.1 500 Internal Server Error
{"status":500,"title":"Internal Server Error","detail":"Something went wrong on our side."}
```

`console.error(err)` writes the whole error to the terminal, starting with `MongoNetworkError: connect ECONNREFUSED` and the database's address, so you can find the cause. The caller gets one calm sentence and none of the details: an error's text can name your database's address, its collections and its indexes, and none of that is anyone else's business.

## Do it: choose the status for an application error

The center keeps adoption applications in their own collection. A unique index lets a person apply for each pet only once, and a validator needs every application to have an email. The applications API's error handler needs one function that picks the status for an error.

**Your job:** write `statusFor(error)`.

- `error`: the error that reached the error handler, an object. When MongoDB refused a write, `error.code` is MongoDB's number for the reason. Other errors have no `code`.
- Return `409` when `error.code` is `11000`: the person already applied for that pet.
- Return `400` when `error.code` is `121`: the validator refused the application.
- Return `500` for every other error: one with another code, such as `13`, and one with no `code` at all, such as a `MongoNetworkError` when MongoDB is down.

Worked through: for `{ name: "MongoServerError", code: 11000 }`, the code is 11000, a duplicate application, so `statusFor` returns `409`.

Practiced live on the lesson page: write the JavaScript right there and check it.

## Check yourself

2 questions to try on the lesson page.

## So what

An API that answers 400, 404, 409 and 500 in the right places tells people exactly what to fix, and tells you when it's yours to fix.

## Key terms

- [Duplicate Key Error](https://www.ask-codey.com/glossary/duplicate-key-error)
- [400 Bad Request](https://www.ask-codey.com/glossary/400-bad-request)
- [404 Not Found](https://www.ask-codey.com/glossary/404-not-found)
- [409 Conflict](https://www.ask-codey.com/glossary/409-conflict)
- [500 Internal Server Error](https://www.ask-codey.com/glossary/500-internal-server-error)
- [Error-Handling Middleware](https://www.ask-codey.com/glossary/error-handling-middleware)

## Related

- [A Data Layer: One File That Talks to the Database](https://www.ask-codey.com/lessons/mongodb-driver-a-data-layer)
- [Schema Validation with $jsonSchema](https://www.ask-codey.com/lessons/mongodb-schema-validation)
- [Unique and Text Indexes](https://www.ask-codey.com/lessons/mongodb-unique-and-text-indexes)

Source: https://www.ask-codey.com/lessons/mongodb-driver-when-the-database-says-no
