How to Write Clear API Error Messages in English

An API error message is a piece of English writing. Most developers do not think of it that way — they think of it as a technical artifact, a status code, a JSON field. But the moment a developer reads your error message at 11 PM while debugging a production issue, it becomes a communication. A clear message saves hours. A bad one causes confusion, support tickets, and eroded trust in your API.

This guide teaches the English writing principles behind effective API error messages, with real examples and the phrases that work.

The Four Qualities of a Good Error Message

A good API error message is:

1. Specific — it tells the developer exactly what went wrong
2. Actionable — it suggests what the developer should do next
3. Non-blaming — it does not make the developer feel stupid
4. Consistent — it follows a predictable format across your API

Most bad error messages fail on specificity and actionability. “An error occurred” fails on both.

Structure of an API Error Response

A well-structured error response in JSON typically includes:

{
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "The 'email' field must be a valid email address.",
    "details": [
      {
        "field": "email",
        "issue": "Value 'user@' is not a valid email address."
      }
    ],
    "request_id": "req_8Kx92mPzA1"
  }
}

The message field is where English writing matters most. Let us look at how to write it well.

Writing the Error Message Field

Be Specific About What Failed

Bad: “Invalid input.” Good: “The ‘start_date’ parameter must be in ISO 8601 format (e.g., ‘2026-06-23’).”

Bad: “Authentication failed.” Good: “The API key provided is invalid or has been revoked. Check your key in the dashboard at https://app.example.com/settings/api-keys.”

Bad: “Resource not found.” Good: “No project was found with ID ‘proj_abc123’. The project may have been deleted or the ID may be incorrect.”

Notice the pattern: name the field or resource, describe the exact problem, and (when possible) provide an example of a valid value.

Use Active Voice and Direct Language

Passive voice makes error messages vague and hard to act on.

Passive (avoid): “The request could not be processed due to missing fields.” Active (prefer): “Your request is missing required fields: ‘name’ and ‘currency’.”

Passive (avoid): “Rate limits were exceeded.” Active (prefer): “You have exceeded the rate limit of 100 requests per minute. Your limit resets at 14:32 UTC.”

Suggest the Next Step

The most valuable thing an error message can do is tell the developer what to do next.

Key phrases for actionable messages:

• “Retry the request after…”
• “Provide a valid value for…”
• “Check that… before calling this endpoint.”
• “See the documentation at [URL] for a list of valid values.”
• “Contact support at support@example.com if this issue persists.”

Use Consistent Sentence Structure

If your 400 errors follow one pattern and your 403 errors follow another, developers have to think about format instead of content. Establish a template and stick to it.

Template for validation errors: “The ‘[field_name]’ [field or parameter] [description of problem]. [Example of valid value or link to docs].”

Template for permission errors: “Your API key does not have permission to [action]. [How to get permission or what role is required].”

Template for rate limit errors: “You have exceeded the [type] limit of [limit] [unit]. [When it resets or how to increase it].”

HTTP Status Codes and the English They Imply

Understanding status codes helps you write the right message:

• 400 Bad Request — the client sent something wrong. The message should explain what and how to fix it.
• 401 Unauthorized — the client is not authenticated. Tell them how to authenticate.
• 403 Forbidden — the client is authenticated but lacks permission. Explain what permission is needed.
• 404 Not Found — the resource does not exist. Confirm the ID and suggest checking whether it was deleted.
• 409 Conflict — a state conflict (e.g., duplicate entry). Explain what already exists.
• 422 Unprocessable Entity — semantically invalid input (even if syntactically correct). List the violated constraints.
• 429 Too Many Requests — rate limited. State the limit and the reset time.
• 500 Internal Server Error — server-side fault. Do not expose internals; provide a request ID for support.

Anti-Patterns to Avoid

Stack Traces in Production

Never expose internal stack traces to API consumers. They reveal implementation details and are useless to most developers. Instead: “An unexpected error occurred. Reference ID: req_9Lm4xZp7B2. Contact support if this persists.”

Overly Technical Internal Names

Bad: “NullPointerException in PaymentGatewayAdapter.processCharge()” Good: “The charge could not be processed. Please check that the ‘amount’ field is greater than zero and that a valid payment method is attached to the customer.”

Generic “Something went wrong”

This message contains zero information. It is the error message equivalent of a shrug. Every error your API returns should be specific enough that a developer can take an action.

Inconsistent Capitalization and Punctuation

Your error messages are part of your API surface. Treat them like code. If some messages end with a period and others do not, if some are sentence case and others are title case, developers will notice the inconsistency and trust your API less.

Key Vocabulary

• Error code — a machine-readable identifier for the error type (e.g., INVALID_PARAMETER)
• Error message — the human-readable description
• Request ID — a unique identifier for the specific API call, useful for debugging
• Rate limit — the maximum number of requests allowed in a time window
• Validation — checking that input meets required constraints
• Constraint — a rule that input must satisfy (e.g., “must be positive”, “max 255 characters”)
• Idempotent — an operation that can be safely retried without side effects
• Retry-After — an HTTP header indicating when the client may retry after being rate-limited

Writing clear API error messages is a form of technical empathy. You are writing for a developer who is tired, under pressure, and needs your message to be a flashlight, not a wall. Write with that developer in mind, and your API will be significantly better to work with.

Navigating the Nuances: Error Messages for Non-Native Speakers

Writing effective API error messages isn’t just about stating what went wrong; it’s about communicating that information clearly and constructively. For developers whose first language isn’t English, this can be particularly challenging. Beyond simply translating technical terms, there’s a subtle art to phrasing errors in a way that’s easily understood, avoids ambiguity, and encourages swift resolution. A poorly worded error message can lead to frustrating debugging sessions, wasted time, and ultimately, a negative developer experience – something we want to avoid at all costs.

One crucial aspect often overlooked is the use of more formal, precise language when crafting these messages. While informal phrasing might seem quicker initially, it risks introducing unnecessary complexity for someone still building their professional English vocabulary. For instance, instead of saying “Something went wrong!” (which is vague and doesn’t offer any guidance), consider “The request failed due to a validation error: the required field ‘email’ was not provided.” This immediately tells the developer what needs fixing – they need to add an email address. Similarly, in a Slack message explaining a bug, avoid saying “It’s broken!” and instead write, “I encountered a 400 Bad Request error when attempting to create a new user. The server returned an error indicating that the ‘username’ field was missing.”

Let’s look at a practical scenario: during code review, you spot a comment from a teammate stating, “This returns a 500 error – needs more detail.” A helpful and professional response would be, “I agree; while a 500 error indicates a server-side issue, it doesn’t pinpoint the root cause. Adding a log statement within the handler to capture the specific exception type and message will significantly aid debugging.” This demonstrates not only an understanding of the problem but also proactively suggests a solution – adding more granular logging is a common best practice that many developers may still be unfamiliar with in terms of its precise English terminology. Remember, providing context beyond just the error code itself is key.

Finally, when writing PR descriptions for errors, focus on why the issue occurred and what steps were taken to resolve it. Instead of “Fixed 500 error,” try: “Resolved a 500 Internal Server Error caused by an unhandled exception during user authentication. Implemented robust error handling with detailed logging and added a conditional check for valid credentials before proceeding.” This level of detail, using clear and descriptive vocabulary, ensures that anyone reviewing the change – including those new to English – can quickly understand the problem and its solution.