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

APIs & Integration

What Is an API Error Message and How Do You Design a Good One?

APIs & Integration · Published · Updated · 9 min read · By BA Mentorship Editorial (AI-written)

Part of our guide to business analyst skills.

What an API error message is

An API error message is the reply an API sends when it cannot do what the caller asked. The caller might be a mobile app, a website or a partner's system. Instead of the data it expected, it gets back a status code and a short body that explains what went wrong. If APIs are new to you, read APIs for Business Analysts first, then come back here.

A well designed error response has several layers. Each layer serves a different reader:

  • HTTP status code: a number such as 400, 404 or 409 that tells the calling software the general type of problem. Machines read this first.
  • Error code: a stable text label such as PARCEL_TOO_HEAVY. Developers write logic against it, so it must not change once published.
  • Message: one or two plain sentences for the developer, tester or support person reading it.
  • Details: which field failed, what value was allowed, or a list of several problems found together.
  • Trace ID: a reference number that support staff can search in the logs to find the exact request.

Think of it like this. The status code gives the category. The error code gives the exact business reason. The message explains it to a human. Some teams follow a published internet standard called Problem Details for HTTP APIs for the shape of the body. Whatever shape your team picks, use it on every endpoint, so callers only have to learn it once.

The three main parts of an API error

AspectStatus codeError codeMessage
Example422PARCEL_TOO_HEAVYParcel weight is over the limit for one parcel.
Main readerCalling software, gateways, monitoring toolsCode in the calling appDevelopers, testers, support staff
Can it change later?Meanings are fixed by the HTTP standardNo, never once publishedYes, wording can be improved
How specificBroad category of problemOne exact business reasonHuman explanation plus next step
Each part answers a different question for a different reader. A good error response includes all three.

Why API error messages matter to business analysts

Error messages look like a developer topic. In practice, most of their content is business knowledge. A developer knows that a request failed. The business analyst usually knows why it should fail: the business rule, the limit, the customer status or the policy behind it. That knowledge belongs in the error design.

Poor errors are expensive in quiet ways. Partner developers raise tickets because they cannot tell what to fix. Support staff cannot answer a customer on the phone. Testers cannot write a clear expected result. One vague reply such as 'Bad Request' can create the same question again and again.

Designing error responses also builds several core abilities at once: business rules analysis, precise writing and close work with developers. See Business Analyst Skills for how these skills fit together.

How to design an API error message, step by step

  1. List the failure cases from the business rules. Walk through every rule, validation and status. For each input, ask: what if it is missing, wrong, too big, already used or not allowed? Include rules from other systems the API depends on.
  2. Pick the status code for each case. Use 400 for a badly formed request, 401 and 403 for identity and permission problems, 404 when the thing does not exist and 409 for conflicts such as duplicates. For a business rule break, teams pick 422 or 400: agree one rule and write it down.
  3. Give each case a stable error code. Use uppercase words joined by underscores. Describe the business reason, not the screen. Never reuse a code for a different meaning.
  4. Write the message. Say what went wrong, show the value that caused it if that is safe, and say what the caller can do next. Use plain words and one idea per sentence.
  5. Add details and a trace ID. Name the failing field using the same path as the request body. Where possible, return all validation problems together so the caller can fix them in one attempt.
  6. Review security and privacy. Remove stack traces, server names, database names and personal data about anyone other than the caller. For login and account lookups, do not reveal whether an account exists.
  7. Document and test it. Add every error to the API contract and to an error catalogue, then write acceptance criteria and negative test cases for the important ones.

For step 2, REST API Status Codes for Business Analysts explains each code in plain words, and MDN's status code reference lists them all.

Designing an API error message7 steps in order: 1. List failure cases: Walk every business rule, validation and status, and ask what could be missing, wrong or not allowed. 2. Pick the status code: Place each case under one HTTP status code, using the rules your team has agreed and written down. 3. Assign a stable error code: Give each business reason an uppercase code that will never change meaning once published. 4. Write the message: Say what went wrong and what the caller can do next, in plain words. 5. Add field and trace ID: Point to the failing field and include a reference that support can search in the logs. 6. Review security: Remove stack traces, internal names and personal data about other people. 7. Document and test: Add the error to the API contract and error catalogue, then write acceptance criteria.1List failure casesWalk every business rule, validation andstatus, and ask what could be missing,wrong or not allowed.2Pick the status codePlace each case under one HTTP statuscode, using the rules your team hasagreed and written down.3Assign a stable error codeGive each business reason an uppercasecode that will never change meaning oncepublished.4Write the messageSay what went wrong and what the callercan do next, in plain words.5Add field and trace IDPoint to the failing field and include areference that support can search in thelogs.6Review securityRemove stack traces, internal names andpersonal data about other people.7Document and testAdd the error to the API contract anderror catalogue, then write acceptancecriteria.
Start from the business rules and finish with documentation and tests. Each step adds one layer of the error response.
Diagram in words
  • 1. List failure cases: Walk every business rule, validation and status, and ask what could be missing, wrong or not allowed.
  • 2. Pick the status code: Place each case under one HTTP status code, using the rules your team has agreed and written down.
  • 3. Assign a stable error code: Give each business reason an uppercase code that will never change meaning once published.
  • 4. Write the message: Say what went wrong and what the caller can do next, in plain words.
  • 5. Add field and trace ID: Point to the failing field and include a reference that support can search in the logs.
  • 6. Review security: Remove stack traces, internal names and personal data about other people.
  • 7. Document and test: Add the error to the API contract and error catalogue, then write acceptance criteria.

What good message wording looks like

Compare two messages for the same problem. Weak: 'Invalid input.' Strong: 'Delivery postcode is missing. Add deliveryAddress.postcode and send the request again.' The strong version names the field, explains the problem and gives the next step. A developer can fix it without opening a ticket.

Remember that the API message is usually written for developers and support staff. The text a customer sees on screen is often written by the app team, who map each error code to friendly, translated wording. Agree early who owns that customer-facing text.

Worked example: a booking API at Brightway Courier

Brightway Courier is a fictional delivery company. Online shops send parcel bookings to its booking API. Shops have complained that when a booking fails, they only get 400 Bad Request with an empty body. Nadia, the business analyst, runs a refinement session with Mei, the lead developer, and Sunil, the operations lead.

The key business rule is simple: Brightway accepts parcels up to 30 kg each. Anything over 30 kg per parcel must go through Brightway Freight, a separate service.

Turning a vague error into a useful one

Brightway Courier, a fictional delivery company, during backlog refinement for the partner booking API.

  1. Sunil Operations lead

    Shops keep calling us when bookings fail. They read me the error and it just says Bad Request. My team cannot tell them what to fix.

  2. Nadia Business analyst

    Which failure do you hear about most often?

  3. Sunil Operations lead

    Heavy parcels. A shop sends a 35 kg parcel and does not realise our limit is 30 kg per parcel.

  4. Mei Lead developer

    Today the validator throws one generic error for everything. I can return a specific code per rule if someone lists the rules.

  5. Nadia Business analyst

    I will draft an error catalogue from the business rules. For weight, the message should give the actual weight, the limit and the next step.

  6. Mei Lead developer

    I will add the field path too, so their developers can highlight the right input on their screen.

  7. Sunil Operations lead

    Please add a reference we can search as well. Then my team can find the exact request when a shop calls.

The people and the company in this scene are fictional.

The business analyst collects the rules, the developer shapes the response, and operations adds what support needs.

Mei and Nadia agree one team rule: 400 for badly formed requests and 422 for requests that break a business rule. Nadia then drafts the response for the heavy parcel case.

Error response for a parcel over the weight limit

Response to POST /bookings, status 422

{

"error": {

"code": "PARCEL_TOO_HEAVY",1

"message": "Parcel weight is 35 kg. The limit is 30 kg per parcel. Book large items with Brightway Freight.",2

"field": "parcel.weightKg",3

"traceId": "bw-7f3a91"4

}

}

  1. Stable error code. Partner apps build logic on this value. It names the business reason and will not change, even if the message wording improves later.
  2. Message with a next step. States the actual weight, the limit and what to do next. It says per parcel, so the reader knows exactly what the rule counts.
  3. Field path. Matches the name used in the request body, so the partner's app can point the user to the right input.
  4. Trace ID. Support staff search the logs with this reference. It contains no customer data.
A shop sent one parcel weighing 35 kg. The limit is 30 kg per parcel, so the booking is rejected with a clear reason.

Next, Nadia writes acceptance criteria in Gherkin so Riya, the QA tester, can test both sides of the limit. If this format is new, see Acceptance Criteria and Gherkin Examples.

GHERKIN

Feature: Partner booking errors

  Scenario: Parcel over the weight limit is rejected
    Given a partner sends a booking with one parcel weighing 35 kg
    And the weight limit is 30 kg per parcel
    When the booking API validates the request
    Then the response status is 422
    And the error code is PARCEL_TOO_HEAVY
    And the error field is parcel.weightKg
    And no booking is created

  Scenario: Parcel exactly at the limit is accepted
    Given a partner sends a booking with one parcel weighing 30 kg
    When the booking API validates the request
    Then the response status is 201
    And a booking is created

Her first error catalogue has five entries:

  • MISSING_FIELD (400): a required field is absent. The message names the field.
  • PARCEL_TOO_HEAVY (422): a parcel weighs over 30 kg.
  • POSTCODE_NOT_SERVED (422): Brightway does not deliver to the destination postcode.
  • BOOKING_NOT_FOUND (404): the booking reference does not exist for this partner.
  • DUPLICATE_BOOKING (409): the shop already sent a booking with the same order reference.

Notice the words 'for this partner' in BOOKING_NOT_FOUND. If one shop asks about another shop's booking, it gets the same 404. The API never reveals that someone else's booking exists.

Common mistakes when designing API error messages

  • One generic error for everything. 'Something went wrong' forces every caller to contact support.
  • The wrong status code. Returning 200 with an error hidden in the body hides the failure from monitoring and from the caller's code. Returning 500 for a caller's mistake makes it look like your system is down.
  • Renaming error codes. Partner apps check these values. Changing one breaks their logic. Improve the message wording instead.
  • Leaking internals. Stack traces, table names and server paths confuse readers and help attackers.
  • Puzzling text. 'Illegal value' or 'Error 1043' tells the reader nothing. Say what is wrong and what to do.
  • Returning only the first problem. If a request has three problems, list all three so the caller fixes them in one go.
  • Forgetting the end user. Nobody owns the customer-facing wording, so raw developer messages appear on screen.

Error message habits

Good habit

  • Use one error format across every endpoint.
  • Name the failing field and the allowed value or range.
  • Keep error codes stable and listed in the API contract.
  • Include a trace ID that support can search.

Risky habit

  • Return 200 OK with an error hidden inside the body.
  • Show stack traces, SQL or server names to the caller.
  • Reuse one error code for several different reasons.
  • Write vague text such as Invalid input or Error occurred.
Small habits decide whether an error saves a support call or creates one.

Checklist before you sign off an error design

Use this list in refinement or before the API contract is baselined. Walk through it with the lead developer and a tester.

API error design checklist

  • Every business rule that can reject a request has its own error code.
  • Each error has one HTTP status code, and the team's rule for choosing codes is written down.
  • Messages say what went wrong and the next step, in plain words.
  • Field paths match the request body names exactly.
  • No stack traces, internal names or other people's personal data appear.
  • All errors are listed in the API contract and the error catalogue.
  • Key errors have acceptance criteria and negative test cases.
  • Someone owns the customer-facing wording if the app shows a message.
Tick every item before the error catalogue is treated as agreed.

Frequently asked questions

Is the API error message the same text the user sees on screen?

Not always. The API message is mainly for developers, testers and support staff. Many apps read the error code and show their own friendly, translated text to customers. Agree with the app or UX team who writes that screen text and how each error code maps to it.

Who writes API error messages, the business analyst or the developer?

It is shared work. The business analyst usually supplies the business rules, the reasons and the next steps. The developer decides the technical shape, status codes and implementation. A tester checks that each error behaves as written. The final catalogue should be reviewed by all three.

Should every error have its own HTTP status code?

No. There are only a small number of status codes, and many different errors share one, such as several business rule failures under 422 or 400. The status code gives the category. The error code in the body gives the exact reason.

How much detail is safe to put in an error message?

Give enough for the caller to fix their own request: the field, the rule and the allowed values. Do not include stack traces, server or database names, or data about other customers. For logins and account lookups, avoid messages that reveal whether an account exists. Check your organisation's security guidelines.

Where should I document API error messages?

Put them in the API contract, for example an OpenAPI file, and keep a readable error catalogue on a shared documentation page. Link each important error to its user story and acceptance criteria so testers and support staff can find it.

This article was written by an AI system and published automatically after automated accuracy, safety and quality checks. 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. Spot an error? Email our support team and we will check and correct it.

Key terms in this article

Browse the full glossary

CHECK BEFORE CONTINUING

Keep your work safe