Stop 10 · API IntegrationTopics · 11/16

Error Handling

In short

APIs fail. Wi-Fi drops, servers crash, users type rubbish. Good apps tell people what went wrong and what to do next, instead of freezing on a blank screen.

Gracefully handling failed API calls — network errors, 4xx/5xx responses, timeouts — instead of leaving the UI stuck or silently broken.

The jaadu makes an announcement through a megaphone on a busy railway platform.

Think of it like this

The railway station announcement

When a train is late, a good station announces it: 'Train 12951 is running 40 minutes late, platform changed to 5'. A bad one just goes silent. Your app's error messages are those announcements. Say what happened and what to do.

Watch it happen

Two failures, two messages

App

API

GET /courses/999

1/6The user opens a course link that was deleted last week.

The big ideas

What you need to know

Network errors

No internet or the server is unreachable. fetch rejects. Suggest checking the connection and offer a Retry.

4xx means the request was wrong

400 bad input, 401 not logged in, 403 not allowed, 404 not found. Usually fixable by the user.

5xx means the server broke

Not the user's fault. Apologise, offer a retry, and log it for your team.

Error boundaries

A React error boundary catches crashes during rendering, so one broken widget doesn't blank the whole page.

See it in code

Walk through the code

1function messageFor(err: unknown): string {2  if (err instanceof TypeError) return "You seem to be offline. Check your internet.";3  if (err instanceof ApiError) {4    if (err.status === 401) return "Please log in again.";5    if (err.status === 403) return "You don't have access to this.";6    if (err.status === 404) return "We couldn't find that.";7    if (err.status >= 500) return "Our server had a problem. Try again in a bit.";8    return err.message;9  }10  return "Something went wrong.";11}

1/4fetch throws a TypeError when the network fails, so treat it as offline.

fetch throws a TypeError for network failures. ApiError is your own class thrown when res.ok is false, carrying the status code.

Save yourself the pain

Common mistakes

Oops

catch (e) { console.log(e) } and moving on.

Do this instead

Put the error in state and show a message with a Retry button. Console logs help you, not the user.

Oops

Showing raw messages like 'Unexpected token < in JSON at position 0'.

Do this instead

Map errors to human messages and keep the technical details in your logs.

Your mission

Break your app on purpose

~25 min

Quick check

Your API returns 403. What does that usually mean?

Go deeper

1Build a consistent error-handling wrapper used across all API calls in a project.
2Show user-friendly error messages, not raw error objects or stack traces.
3Handle the specific case of a 401 unauthorized by redirecting to login.