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
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:
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:
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":
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:
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:
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 }
}
}
}
})
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:
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();
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:
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.");
});
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:
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.codeis MongoDB's number for the reason. Other errors have nocode.- Return
409whenerror.codeis11000: the person already applied for that pet. - Return
400whenerror.codeis121: the validator refused the application. - Return
500for every other error: one with another code, such as13, and one with nocodeat all, such as aMongoNetworkErrorwhen 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.