SELF-GUIDED BA PRACTICE Packages available · Access after confirmed paymentSee packages ↗

APIs & Integration

REST API status codes for business analysts

APIs & Integration · Published · Updated · 9 min read · By BA Mentorship Editorial

Part of our guide to business analyst skills.

What a status code is, in plain English

When your browser or another system calls an API, the server replies with a status code: a three-digit number plus a short label. It is the quickest answer to "did that work?". The number is read by software, which decides what to do next: show the data, ask the user to log in again, wait and retry, or raise an alarm. The full catalogue is on the Mozilla page for HTTP response status codes; the glossary entry for HTTP status code gives the short version.

Codes are grouped by their first digit:

GroupMeaningWho needs to act
1xxInformational (rare in business work)Nobody
2xxSuccessNobody; carry on
3xxRedirect: look somewhere elseThe caller follows the new address
4xxClient error: the request was wrongThe caller must fix the request or its permissions
5xxServer error: the provider failedThe provider must fix it; the caller may retry later

If you remember only one thing, remember the 4xx versus 5xx split. It tells you whose problem it is, and therefore who has to act and which team gets the incident.

Why a business analyst should care

Developers choose status codes, but the choice expresses a business rule. Is an expired insurance policy a "not found" or a "forbidden" situation? Should a duplicate claim be rejected or quietly accepted? Those are business decisions, and if the business analyst does not make them explicit, each developer decides differently and partner systems break. Clear status code requirements also make testing straightforward: each business situation becomes one test case with an expected code and message. If you are new to APIs, read APIs for business analysts first; this article goes deeper on responses.

The success codes (2xx)

Shieldline Insurance is a fictional insurer with a claims API. The examples below use it.

CodeNameUse it when
200OKA read or update worked and the response has content
201CreatedA new record was created (usually after a POST); return its ID
202AcceptedThe request was accepted but will be processed later (queued)
204No ContentThe action worked and there is nothing to send back (for example a delete)

Example: submitting a new claim.

POST /v1/claims
{
  "policyNumber": "SL-55012",
  "incidentDate": "2026-09-30",
  "description": "Water damage in kitchen",
  "estimatedAmount": 1800.00
}

HTTP/1.1 201 Created
Location: /v1/claims/CL-70214
{
  "claimId": "CL-70214",
  "status": "received"
}

A requirement here would read: "On successful submission the API returns 201, the new claimId and status received." If processing involves a manual review that takes days, a 202 may be better, because "accepted" is more honest than "done". The BA should ask which one reflects reality.

The client errors (4xx) you will use most

These are where business rules live, so spend time here.

CodeNamePlain meaningShieldline example
400Bad RequestThe request is malformed or unreadableThe JSON is broken, or incidentDate is "yesterday-ish"
401UnauthorizedWe do not know who you are (missing or invalid credentials)No token, or the token has expired
403ForbiddenWe know who you are, but you may not do thisA junior adjuster tries to approve a payout above their limit
404Not FoundThat record or address does not exist (or you may not know it exists)Claim CL-99999 does not exist
409ConflictThe request clashes with the current stateA claim for that policy and incident date already exists
422Unprocessable ContentThe request is well-formed but breaks a business or validation ruleThe incident date is before the policy start date
429Too Many RequestsThe caller exceeded a rate limitMore than 60 calls per minute

401 versus 403 confuses almost everybody. A hotel analogy helps. 401 is the receptionist saying "I do not know who you are; show your ID". 403 is "I know who you are, but your key card does not open that room". The names are historical, which is why 401 is called "Unauthorized" even though it is really about authentication.

400 versus 422 is a judgement call, and teams differ. A common convention: use 400 when the request cannot be understood at all (bad JSON, wrong data type) and 422 when it is understood but fails a rule. Whatever the team picks, write it down once and apply it consistently.

A good error body helps the caller fix the problem without calling your support team:

HTTP/1.1 422 Unprocessable Content
{
  "error": "incident_before_policy_start",
  "message": "Incident date 2026-01-02 is before the policy start date 2026-03-01.",
  "field": "incidentDate"
}

401 Unauthorized

  • The receptionist: “I do not know who you are; show your ID.”
  • Missing or expired token
  • Fix: sign in again, or renew the credentials

403 Forbidden

  • “I know who you are, but your key card does not open that room.”
  • A junior adjuster approving a payout above their limit
  • Fix: roles and permissions
The hotel analogy. 401 is about who you are; 403 is about what you may do. The names are historical, which is why 401 says “Unauthorized”.

The server errors (5xx) and retries

CodeNamePlain meaning
500Internal Server ErrorSomething broke inside the provider; no more detail
502Bad GatewayA middle system got a bad answer from another system behind it
503Service UnavailableThe service is down, overloaded or in maintenance; try again later
504Gateway TimeoutA middle system waited too long for the system behind it

For the business, the questions are about recovery. If Shieldline's payment system returns 503 while a claim payout is being sent, what should the claims system do? A sensible requirement: "On 502, 503 or 504 the integration retries up to 3 times with increasing delay; after that, the payout is marked Pending, an alert goes to the operations team and the claimant sees 'We are processing your payment'." Also decide what must never be retried blindly. Retrying a payout without protection against duplicates could pay twice, which is why the safe-retry idea (idempotency) in the API guide matters.

Never expose internal details such as stack traces or database names in a 500 response. The user message should be calm and useful; the technical detail belongs in logs.

  1. 502, 503 or 504The payment system fails while a payout is sent.
  2. Retry up to 3 timesWith increasing delay, using a safe-retry key.
  3. Still failingThe payout is marked Pending and operations get an alert.
  4. The claimant sees“We are processing your payment.”
The sample recovery rule as a flow. Retries need protection against duplicates, or a payout could be sent twice.

Step by step: choosing the right code for a business rule

Choosing a status code by asking questions in order1. Was the request understood? No: 400. 2. Do we know who is calling? No: 401. 3. Are they allowed to do this? No: 403 or 404. 4. Does the thing exist? No: 404. 5. Does it clash with the current state? Yes: 409. 6. Does the content break a rule? Yes: 422. 7. Is the caller simply too fast? Yes: 429. Otherwise: Success: 200, 201, 202 or 204.Was the request understood?No400YesDo we know who is calling?No401YesAre they allowed to do this?No403 or 404YesDoes the thing exist?No404YesDoes it clash with thecurrent state?Yes409NoDoes the content break arule?Yes422NoIs the caller simply toofast?Yes429NoSuccess: 200, 201, 202 or204
Ask the questions in this order. The first answer that leaves the chain is the code. For “allowed?”, decide deliberately between 403 and 404 so you do not reveal that a record exists.
Diagram in words
  • Was the request understood? No: 400
  • Do we know who is calling? No: 401
  • Are they allowed to do this? No: 403 or 404
  • Does the thing exist? No: 404
  • Does it clash with the current state? Yes: 409
  • Does the content break a rule? Yes: 422
  • Is the caller simply too fast? Yes: 429
  • Otherwise: Success: 200, 201, 202 or 204
  1. Describe the situation in business words. "A customer tries to open someone else's claim."
  2. Ask: was the request understood? If not, 400.
  3. Ask: do we know who is calling? If not, 401.
  4. Ask: are they allowed? If not, 403 or, to avoid revealing that a record exists, 404. Decide deliberately.
  5. Ask: does the thing exist? If not, 404.
  6. Ask: does it clash with the current state? Duplicate or already-closed items are 409.
  7. Ask: does the content break a rule? 422 with a clear field and message.
  8. Ask: could the caller simply be too fast? 429 with a Retry-After header.
  9. Otherwise success. Pick 200, 201, 202 or 204 to match what really happened.

Then record the answer in a table, one row per scenario:

ScenarioCodeError codeCustomer message
Claim submitted201(none)We have received your claim.
Token missing or expired401unauthenticatedPlease sign in again.
Open another customer's claim404claim_not_foundWe cannot find that claim.
Duplicate claim409duplicate_claimA claim for this incident already exists.
Incident before policy start422incident_before_policy_startThe incident date is before your policy began.
Too many requests429rate_limitedPlease wait a minute and try again.

This scenario table converts directly into test cases and acceptance criteria. See acceptance criteria examples for wording.

Reading codes when something fails

A tester or BA often lands in a conversation that starts "the integration is broken". The status code is the first clue to who owns the problem:

  • 401: check credentials or token expiry. Often a configuration or access request, not a bug.
  • 403: check roles and permissions in the provider's system.
  • 404: check the URL, the ID and the environment (a record that exists in production may not exist in the test system).
  • 400 or 422: compare the request body with the documentation. Look at the error body for the field name.
  • 429: slow down, batch calls or ask for a higher limit.
  • 500, 502, 503, 504: raise it with the provider, with the time, the request ID and the endpoint.

Attach the request (without secrets), the response code and body, the time and the environment to the bug report. That single habit halves the back-and-forth. In a Jira ticket this goes under actual result.

Common mistakes

  • ✅ Specify a status code and message for every business rule. ⚠️ Writing "show an error" with no detail.
  • ✅ Return 4xx for caller mistakes and 5xx for provider failures. ⚠️ Returning 200 with an error hidden inside the body, which breaks monitoring and client logic.
  • ✅ Use consistent error body fields across the API. ⚠️ A different error shape for every endpoint.
  • ✅ Decide when to hide existence (404 instead of 403). ⚠️ Leaking whether an account or claim exists.
  • ✅ Define retry and timeout behaviour for 5xx and 429. ⚠️ Unlimited retries that hammer a struggling system.
  • ✅ Write user-friendly messages separate from technical ones. ⚠️ Showing raw error text from the server to customers.
  • ✅ Test every scenario in the table. ⚠️ Only testing the happy path before go-live.

Reader exercise

For each situation below, pick a status code and write one sentence for the customer message. Then compare with a friend.

  1. A customer uploads a photo larger than the allowed size for a claim.
  2. A customer logs in but tries to view another customer's policy.
  3. The payment provider is down for maintenance.
  4. A customer submits the same claim twice by double-clicking.
  5. A request arrives with a mistyped date format.

There can be more than one defensible answer for some, for example 400 or 422 for the date. The skill is choosing, writing the rule down and being consistent.

Practise in the BA Lab

In stage 7 of the BA Lab you send requests to a mock API for a fictional company, read the responses and decide whether the status code is right for the business rule. The checks explain why a wrong code matters and how to fix it. It is practice with made-up data, not a live system. See the pricing page to find which packages include the API stage.

Frequently asked questions

What is the difference between 401 and 403?

401 means the system does not know who you are (missing or invalid credentials). 403 means it knows who you are but you are not allowed to do that action.

Should I use 400 or 422 for validation errors?

Both are used. A common convention is 400 for unreadable or malformed requests and 422 for well-formed requests that break a business rule. Agree one convention in the team and document it.

Is it acceptable for an API to return 200 with an error in the body?

It is poor practice because monitoring tools and client code rely on the status code. Use a 4xx or 5xx code for failures and put details in the response body.

What does a 500 error mean for the business?

The provider failed in a way it did not expect. The caller cannot fix it by changing the request. Define retry, alerting and customer messaging in the requirements.

Do I need to memorise all HTTP status codes?

No. Know the groups (2xx, 4xx, 5xx) and about ten common codes, and look up the rest in the Mozilla HTTP status reference.

This article is educational. All companies, people and numbers in the examples are fictional. BA Mentorship does not issue professional certifications and cannot guarantee any job or interview outcome.

Key terms in this article

Browse the full glossary

CHECK BEFORE CONTINUING

Keep your work safe