Mastering Error Codes: Best Practices for Clear, Scalable Error Handling

Challenges of Designing Error Codes and Messages

Predicting every possible failure early in a project is difficult. Designers must balance completeness with flexibility while providing information that is useful for developers and understandable for end users.

Best Practices

Systematic Error Classification

Create a hierarchical taxonomy (e.g., ERR_{domain}_{severity}_{code}) so that related errors are grouped together, making the codebase easier to navigate and maintain.

Error‑Code Templates

Use a template that incorporates error type, source module, and severity. For example, USR_01_1001 could represent a user‑input validation error in module 01 with sequence 1001.

Dynamic Error Messages

Generate messages at runtime using placeholders that are filled with context data, e.g., "File \"{filename}\" not found in directory {dir}.". This provides precise, actionable feedback.

Reserve Ranges for Future Extensions

Allocate numeric or lexical ranges for each error domain (e.g., 1000‑1999 for authentication, 2000‑2999 for storage) so new errors can be added without renumbering existing codes.

Documentation and Automation

Maintain a single source of truth (e.g., a Markdown file or a JSON schema) that lists every code and its message. Integrate linting or CI checks that reject pull requests containing undocumented or duplicate codes.

User‑Friendly Messages

Write messages in plain language, avoid technical jargon, and include a suggested next step, such as "Check the file path and try again".

Open‑Source Specifications and Templates

HTTP Status Codes

Defined by IETF/W3C, these codes illustrate a clear classification hierarchy that can be adapted for non‑HTTP systems.

1xx – Informational

2xx – Success

3xx – Redirection

4xx – Client error

5xx – Server error

gRPC Status Codes

gRPC defines its own set of status codes for RPC results, useful for non‑Web services. Reference: https://grpc.io/docs/guides/status-codes/

Microsoft REST API Guidelines

Provides recommendations for error handling and response formats in RESTful APIs. Reference: https://github.com/microsoft/api-guidelines/blob/vNext/Guidelines.md#710-response-status-codes

Google JSON Style Guide

Specifies a JSON error object structure that can be adapted to other payload formats. Example:

{
  "apiVersion": "2.0",
  "error": {
    "code": 404,
    "message": "File Not Found",
    "errors": [{
      "domain": "Calendar",
      "reason": "ResourceNotFoundException",
      "message": "File Not Found"
    }]
  }
}

Linux System Error Codes (errno)

Unix‑like systems define error constants in errno.h. On Ubuntu, install moreutils and list the codes with errno -l:

EPERM 1 Operation not permitted
ENOENT 2 No such file or directory
ESRCH 3 No such process
EINTR 4 Interrupted system call
EIO 5 Input/output error
ENXIO 6 No such device or address
E2BIG 7 Argument list too long
ENOEXEC 8 Exec format error
EBADF 9 Bad file descriptor
ECHILD 10 No child processes
EAGAIN 11 Resource temporarily unavailable
ENOMEM 12 Cannot allocate memory
EACCES 13 Permission denied
EFAULT 14 Bad address
ENOTBLK 15 Block device required
EBUSY 16 Device or resource busy
EEXIST 17 File exists
EXDEV 18 Invalid cross-device link
ENODEV 19 No such device
ENOTDIR 20 Not a directory
EISDIR 21 Is a directory
EINVAL 22 Invalid argument
ENFILE 23 Too many open files in system
EMFILE 24 Too many open files
ENOTTY 25 Inappropriate ioctl for device
ETXTBSY 26 Text file busy
EFBIG 27 File too large
ENOSPC 28 No space left on device
ESPIPE 29 Illegal seek
EROFS 30 Read-only file system
EMLINK 31 Too many links
EPIPE 32 Broken pipe
EDOM 33 Numerical argument out of domain
ERANGE 34 Numerical result out of range
EDEADLK 35 Resource deadlock avoided
ENAMETOOLONG 36 File name too long
ENOLCK 37 No locks available
ENOSYS 38 Function not implemented
ENOTEMPTY 39 Directory not empty
ELOOP 40 Too many levels of symbolic links
ENOMSG 42 No message of desired type
EIDRM 43 Identifier removed
ECHRNG 44 Channel number out of range
EL2NSYNC 45 Level 2 not synchronized
EL3HLT 46 Level 3 halted
EL3RST 47 Level 3 reset
ELNRNG 48 Link number out of range
EUNATCH 49 Protocol driver not attached
ENOCSI 50 No CSI structure available
EL2HLT 51 Level 2 halted
EBADE 52 Invalid exchange
EBADR 53 Invalid request descriptor
EXFULL 54 Exchange full
ENOANO 55 No anode
EBADRQC 56 Invalid request code
EBADSLT 57 Invalid slot
EBFONT 59 Bad font file format
ENOSTR 60 Device not a stream
ENODATA 61 No data available
ETIME 62 Timer expired
ENOSR 63 Out of streams resources
ENONET 64 Machine is not on the network
ENOPKG 65 Package not installed
EREMOTE 66 Object is remote
ENOLINK 67 Link has been severed
EADV 68 Advertise error
ESRMNT 69 Srmount error
ECOMM 70 Communication error on send
EPROTO 71 Protocol error
EMULTIHOP 72 Multihop attempted
EDOTDOT 73 RFS specific error
EBADMSG 74 Bad message
EOVERFLOW 75 Value too large for defined data type
ENOTUNIQ 76 Name not unique on network
EBADFD 77 File descriptor in bad state
EREMCHG 78 Remote address changed
ELIBACC 79 Cannot access a needed shared library
ELIBBAD 80 Accessing a corrupted shared library
ELIBSCN 81 .lib section in a.out corrupted
ELIBMAX 82 Attempting to link in too many shared libraries
ELIBEXEC 83 Cannot exec a shared library directly
EILSEQ 84 Invalid or incomplete multibyte or wide character
ERESTART 85 Interrupted system call should be restarted
ESTRPIPE 86 Streams pipe error
EUSERS 87 Too many users
ENOTSOCK 88 Socket operation on non-socket
EDESTADDRREQ 89 Destination address required
EMSGSIZE 90 Message too long
EPROTOTYPE 91 Protocol wrong type for socket
ENOPROTOOPT 92 Protocol not available
EPROTONOSUPPORT 93 Protocol not supported
ESOCKTNOSUPPORT 94 Socket type not supported
EOPNOTSUPP 95 Operation not supported
EPFNOSUPPORT 96 Protocol family not supported
EAFNOSUPPORT 97 Address family not supported by protocol
EADDRINUSE 98 Address already in use
EADDRNOTAVAIL 99 Cannot assign requested address
ENETDOWN 100 Network is down
ENETUNREACH 101 Network is unreachable
ENETRESET 102 Network dropped connection on reset
ECONNABORTED 103 Software caused connection abort
ECONNRESET 104 Connection reset by peer
ENOBUFS 105 No buffer space available
EISCONN 106 Transport endpoint is already connected
ENOTCONN 107 Transport endpoint is not connected
ESHUTDOWN 108 Cannot send after transport endpoint shutdown
ETOOMANYREFS 109 Too many references: cannot splice
ETIMEDOUT 110 Connection timed out
ECONNREFUSED 111 Connection refused
EHOSTDOWN 112 Host is down
EHOSTUNREACH 113 No route to host
EALREADY 114 Operation already in progress
EINPROGRESS 115 Operation now in progress
ESTALE 116 Stale file handle
EUCLEAN 117 Structure needs cleaning
ENOTNAM 118 Not a XENIX named type file
ENAVAIL 119 No XENIX semaphores available
EISNAM 120 Is a named type file
EREMOTEIO 121 Remote I/O error
EDQUOT 122 Disk quota exceeded
ENOMEDIUM 123 No medium found
EMEDIUMTYPE 124 Wrong medium type
ECANCELED 125 Operation canceled
ENOKEY 126 Required key not available
EKEYEXPIRED 127 Key has expired
EKEYREVOKED 128 Key has been revoked
EKEYREJECTED 129 Key was rejected by service
EOWNERDEAD 130 Owner died
ENOTRECOVERABLE 131 State not recoverable
ERFKILL 132 Operation not possible due to RF‑kill
EHWPOISON 133 Memory page has hardware error
ENOTSUP 95 Operation not supported

Conclusion

Applying systematic classification, templated generation, context‑aware messages, and automated documentation enables a robust, extensible error‑handling framework. Open‑source specifications such as HTTP, gRPC, Microsoft REST guidelines, Google JSON style, and Linux errno provide proven patterns that can be adapted to suit any software project.