Standard Errors

Summary

Standard Errors is a small standard for user-facing failure messages.

It gives every unexpected failure clear content: what happened, what was affected, what to do next, and a stable code that support and engineering teams can search for.

A Standard Errors diagnostic includes these fields:

This standard defines what information a diagnostic contains. It does not define the visual layout, punctuation, labels, ordering, component shape, or transport format.

Use Standard Errors when something broke unexpectedly. Do not use it for normal product outcomes such as validation feedback, permission denial, quota limits, file size limits, empty states, or upgrade prompts.

Specification

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.

1. A diagnostic MUST describe an unexpected system failure.
2. A diagnostic MUST include a severity, code, summary, and description.
3. Severity MUST be Error or Warning.
4. The code MUST be stable, unique within the application that emits it, visible to the user, and easy to search for. A source search for the code SHOULD lead an engineer to the line that generated the diagnostic.
5. The summary MUST say what failed in plain language.
6. The description MUST explain what happened. The description SHOULD explain why it happened in non-technical language.
7. The impact SHOULD say what was saved, sent, charged, deleted, changed, or left untouched when that is not obvious.
8. A diagnostic MUST include a resolution with a concrete next step, or a clear way out when the user cannot fix the issue.
9. A diagnostic SHOULD include a reference link to help docs, a status page, support instructions, or a runbook the audience can access when one is available.
10. A trace ID SHOULD be included when it helps support or engineering find the specific occurrence.
11. A diagnostic MUST NOT expose stack traces, raw exception messages, secrets, tokens, private data, user identifiers such as email addresses or account IDs, SQL errors, internal hostnames, or internal service names.
12. A diagnostic MUST NOT hide a known specific failure behind a generic message such as Something went wrong. When the failure class is genuinely unknown, the diagnostic MUST still include a stable code identifying the unknown-failure path, and SHOULD include a trace ID.

Fields

Severity

Use one of these values:

• Error - the requested operation failed.
• Warning - the operation completed with an unexpected limitation or degraded result.

Code

The code identifies the class of problem. It is for support, docs, and source search. It should be unique within the application that emits it so a search leads an engineer directly to the line that generated the diagnostic.

Products may use any code format that fits their codebase, support process, and documentation style. The code must be stable, unique, safe to show to users, and easy to search for.

These are all valid styles:

AUTH001
EXPORT-002
account.connection.unavailable
sync/offline/not-sent
Backup.Media.Partial

Each product SHOULD choose one code style and use it consistently.

Do not put timestamps, user IDs, environment names, or trace IDs in the code.

Summary

The summary is a short statement of what happened.

Good:

Could not save changes

Bad:

Something went wrong

Description

The description explains the failure without leaking implementation detail. It should say why the failure happened when the product knows enough to say so.

Use plain, user-friendly cause language, such as due to a technical issue on our end, because the connection was interrupted, or because file storage did not respond in time. Do not expose raw dependency names, stack traces, database errors, exception messages, or internal service names.

Say what happened, why it happened, and what did not happen when the user might worry about it. Keep it short.

Impact

Impact explains the result for the user. Include it when the consequence is not obvious.

Useful impact answers questions like:

• Was anything saved, sent, charged, created, deleted, or changed?
• Is the current work safe?
• Can the user keep going with a partial result?
• Which file, account, workspace, or operation is affected?

Resolution

Resolution tells the user what to do next.

Good resolutions are concrete:

• Retry now.
• Retry later.
• Use the partial result.
• Contact support and include this message.
• Ask an administrator to fix a dependency or setting.
• A concrete series of steps to follow or commands to run.

Do not tell the user to do something unsafe, impossible, or unrelated.

Reference

Reference is recommended whenever a suitable link exists. Use it to link to help docs, support instructions, status pages, or runbooks that provide more information on the issue or resolutions.

Trace ID

Trace ID is optional. It identifies one occurrence of the problem. It must be safe to share and copy as one value. It should be included when it helps support or engineering find the specific occurrence in logs, traces, or monitoring systems. It should not be included when it does not help or when it would be too difficult to correlate.

The code identifies the kind of problem. The trace ID identifies this instance of that problem.

FAQ

Why use Standard Errors?

Standard Errors gives users clear, calm messages, gives support a code to ask for, helps engineers search for the exact diagnostic, connects logs and traces to what the user saw, and avoids a mix of vague, scary, and inconsistent failures.

Is this an API error format?

No. It is for messages shown to people. APIs, logs, metrics, traces, and exceptions may carry the same code or trace ID, but they are separate formats.

Should validation errors use Standard Errors?

No. Validation feedback is a normal product outcome. Use ordinary field or form guidance instead.

Should permission errors use Standard Errors?

Usually no. If the permission system is working as designed, explain the policy in normal product language. Use Standard Errors only when the system failed in an unexpected way.

Does Standard Errors define the layout?

No. A CLI, web app, mobile app, modal, toast, banner, or dialog can present the fields however it needs to. Keep the same meaning and make the message easy to copy or screenshot.

What makes a code good?

A good code is stable, unique, safe to show to users, and searchable. Each product should choose a format that fits its codebase and support process, then use it consistently. When an engineer searches for the code, they should find the place that generated the diagnostic.

Examples

These examples show the same content contract in different surfaces. They are not required layouts.

CLI: error

Error: EXPORT001 - Could not create export

The export did not finish because file storage did not respond in time.

No export file was created. Project records and attached files were not downloaded.

Wait a few minutes, then run the export again. If it keeps failing, contact support and include this message.

Reference: https://www.example.com/help/export-failed
Trace ID: req_01HX7J3Q9R6W4N2Z0K5M8B1C2D

CLI: warning

------------------------------------------------------------------------
Warning: EXPORT002 - Export completed without attachments
------------------------------------------------------------------------

The export file was created, but attachments could not be added because file storage did not respond before the export finished.

The export includes project records. Attached files are missing.

To resolve:

  * Use this export if you only need project records.
  * Wait a few minutes, then run the export again.
  * If attachments are still missing, contact support and include this message.

------------------------------------------------------------------------
Reference: https://www.example.com/help/export-attachments
Trace ID: req_01HX7J3Q9R6W4N2Z
------------------------------------------------------------------------

Web

This modal puts the user-facing message first and keeps the support identifiers in a quiet footer.

Mobile

This mobile warning uses a compact in-app card instead of a modal.

Desktop GUI

This desktop banner fits into the app surface and pairs the action with the support detail.

Anti-patterns

These are the failure messages Standard Errors exists to replace. If a diagnostic looks like any of these, treat it as a bug.

Generic mystery

Something went wrong. Please try again.

No code, no cause, no impact, no real next step. The user cannot search for it, support cannot ask for it, and engineering cannot find where it came from.

Raw exception

NullPointerException at com.example.svc.OrderProcessor.handle(OrderProcessor.java:142)

Leaks the internal stack, internal service names, and language detail. Says nothing about what the user lost or what to do.

Friendly nothing

Oops! Our hamsters fell off the wheel. Try again later.

Cute tone, zero content. No code, no impact, no resolution. Hides a real failure behind a mascot.

Inaccurate reassurance

Your changes have been saved.

…shown after a save that failed silently. A diagnostic that lies about impact is worse than a generic one.

Code-only

Error: 0x80070005

A code with no human-readable summary, description, or resolution. Standard Errors codes are a search aid, not the message itself.

Mixed responsibilities

Invalid email address. (ERR_VALIDATION_42)

This is normal validation feedback dressed up as a system diagnostic. Use ordinary field guidance for input problems; reserve Standard Errors for unexpected failures.