Error levels: Difference between revisions
No edit summary |
|||
Line 6: | Line 6: | ||
Note that I mostly program in PHP, so 'error', 'exception', and 'assertion' are particular to PHP, but they might apply in other contexts. | Note that I mostly program in PHP, so 'error', 'exception', and 'assertion' are particular to PHP, but they might apply in other contexts. | ||
Note: in the following tables I indicate a corresponding HTTP response code with similar semantics. | Note: in the following tables I indicate a corresponding [https://en.wikipedia.org/wiki/List_of_HTTP_status_codes HTTP response code] with similar semantics. | ||
== Major error levels == | == Major error levels == |
Revision as of 13:18, 9 February 2024
I should have done this a long time ago. I'm going to start allocating standard error levels for my own use.
To be clear, these are process error levels, also known as exit status and error code. I endeavour to allocate particular error levels for my own use in the range [10, 100), comfortably in two-digit territory.
Note that I mostly program in PHP, so 'error', 'exception', and 'assertion' are particular to PHP, but they might apply in other contexts.
Note: in the following tables I indicate a corresponding HTTP response code with similar semantics.
Major error levels
The major error levels are:
- EXIT_BAD_DATA (input error)
- EXIT_BAD_COMMAND (user error)
- EXIT_BAD_ENVIRONMENT (environment error)
- EXIT_BAD_PROGRAM (program error)
You can always use one of the major error levels, but a more specific code is usually better if possible.
My error levels
These are some notes about error levels specifically nominated by me.
Error Level | Category | Constant | HTTP | Meaning | Alternative |
---|---|---|---|---|---|
10 | logic error | EXIT_CANNOT_CONTINUE | 202 | cannot continue; but nothing is abnormal or wrong | consider EXIT_SPECIAL_SUCCESS |
20 | input error | EXIT_BAD_DATA | 404 | there was a problem with inputs | |
21 | input error | EXIT_BAD_FORMAT | 404 | data was in an invalid format | |
22 | input error | EXIT_BAD_VALUE | 404 | data nominated an invalid value (but was in correct format) | |
40 | user error | EXIT_BAD_COMMAND | 400 | invalid command-line or options | |
41 | user error | EXIT_NO_FILE | 400 | a required file/directory path was not nominated | |
42 | user error | EXIT_WRONG_FILE | 400 | user nominated file (or directory) is missing | use EXIT_FILE_MISSING for system files |
43 | user error | EXIT_BAD_FILE | 403 | user nominated file (or directory) cannot be accessed due to invalid permissions | use EXIT_NO_ACCESS for system files |
60 | environment error | EXIT_BAD_ENVIRONMENT | 503 | invalid run-time environment; cannot run | |
61 | environment error | EXIT_FILE_MISSING | 503 | a file (or directory) that is expected to always be available is not available | use EXIT_WRONG_FILE for user nominated files |
62 | environment error | EXIT_NO_ACCESS | 503 | a file (or directory) that should be accessible cannot be accessed due to invalid permissions | use EXIT_BAD_FILE for user nominated files |
63 | environment error | EXIT_BAD_CONFIG | 503 | config file missing or invalid | |
76 | environment error | EXIT_NO_SERVICE | 503 | cannot establish connection to a required service | prefer EXIT_NO_DATABASE for database services |
77 | environment error | EXIT_NO_DATABASE | 503 | cannot establish connection to a required database | |
78 | environment error | EXIT_EXHAUSTED | 507 | resources exhausted; out of memory, disk space, inodes, etc | |
79 | environment error | EXIT_OFFLINE | 503 | system offline; as configured by administrator | |
80 | program error | EXIT_BAD_PROGRAM | 500 | an unhandled and fatal situation encountered | |
81 | program error | EXIT_ERROR | 500 | an error caused process termination | |
82 | program error | EXIT_EXCEPTION | 500 | an unhandled exception caused process termination | |
83 | program error | EXIT_ASSERT | 500 | an assertion violation caused process termination | |
84 | program error | EXIT_TEST_FAILED | 500 | test failed; unit-test did not succeed | |
85 | program error | EXIT_INVALID | 500 | invalid error level; the programmer nominated an invalid error level and the host exited with 85 instead | |
90 | special purpose | EXIT_SPECIAL_SUCCESS | 202 | special operation successful; used for safety (in case improperly invoked) | |
98 | special purpose | EXIT_OPTIONS_LISTED | 200 | program options listed; use when programs can be invoked to list their options in a machine readable format | |
99 | special purpose | EXIT_HELP | 200 | help or version number requested |
Other error levels
These are some notes about how other software uses error levels.
Error Level | Convention | Category | Constant | HTTP | Meaning |
---|---|---|---|---|---|
0 | success | EXIT_SUCCESS | 200 | success! | |
1 | generic | EXIT_GENERIC_1 | 404 | the generic "some problem occurred" value, prefer something more specific | |
2 | generic | EXIT_GENERIC_2 | 404 | incorrect usage or invalid arguments, the 404 of error levels | |
126 | UNIX | UNIX | EXIT_UNIX_BAD_PERMISSION | 403 | command was found but could not be executed due to permissions |
127 | UNIX | UNIX | EXIT_UNIX_BAD_COMMAND | 404 | command not found or could not be executed |
128 | UNIX | UNIX | EXIT_TERMINATED_BY_SIGNAL | 500 | process terminated by signal |
130 | UNIX | UNIX | EXIT_TERMINATED_BY_CTRLC | 500 | process terminated by Ctrl+C |
255 | generic | EXIT_GENERIC_255 | 404 | the other generic "some problem occurred" value, prefer something more specific |
Error level range
The errors are in increasing order of should-not-happenness. Basically:
- logic error: cannot continue now, but nothing is wrong
- input error: invalid data
- user error: invalid options
- environment error: an environment problem, cannot connect to service or incompatible versions etc
- program error: shouldn't happen, a situation the code hasn't handled yet
Whether it's an input error, user error, or environment error is basically a decision for you to make. It's not super important which number you allocate, especially when multiple categories might apply. It's probably best if you try to blame the program or environment more and the user less.
Note that special purpose "success" codes are only used in situations where you want to protect the user from making a mistake. So if a version number is printed because there was a --version command-line argument; or help was printed because there was a --help command-line argument; or if a machine-readable list of options was requested and supplied; then we exit with a non-zero error level even though technically we haven't "failed", we just might have done something by accident that the use didn't expect or intend. The main reason for these options is that when you're running in bash with `set -e` enabled (and usually you should be for most non-interactive situations) then your script will stop if a process returns an error. So we return an error just in case we did something in a script that a user didn't intend. After all if they think they've successfully invoked a command, but all they've actually done is report the version number or displayed the program help text, they'd probably like to know!
Range | Category | Meaning |
1-9 | not much meaning, prefer don't use | |
10-19 | logic error | cannot continue now, but nothing is abnormal or wrong |
20-39 | input error | invalid data |
40-59 | user error | invalid command-line or options |
60-79 | environment error | improper run-time environment |
80-89 | program error | should not happen, unsupported situation |
90-99 | special purpose | success indicators, used for safety |
100+ | some have meanings in UNIX, otherwise don't use |
BASH code
# 2024-02-09 jj5 - SEE: https://www.jj5.net/wiki/Error_levels # EXIT_SUCCESS=0 # success! EXIT_CANNOT_CONTINUE=10 # logic error: cannot continue; but nothing is abnormal or wrong; consider EXIT_SPECIAL_SUCCESS EXIT_BAD_DATA=20 # input error: there was a problem with inputs EXIT_BAD_FORMAT=21 # input error: data was in an invalid format EXIT_BAD_VALUE=22 # input error: data nominated an invalid value (but was in correct format) EXIT_BAD_COMMAND=40 # user error: invalid command-line or options EXIT_NO_FILE=41 # user error: a required file/directory path not nominated EXIT_WRONG_FILE=42 # user error: user nominated file (or directory) missing; use EXIT_FILE_MISSING for system files EXIT_BAD_FILE=43 # user error: user nominated file (or directory) cannot be accessed due to invalid permissions; use EXIT_NO_ACCESS for system files EXIT_BAD_ENVIRONMENT=60 # environment error: invalid run-time environment; cannot run EXIT_FILE_MISSING=61 # environment error: a file (or directory) that is expected to always be available is not available; use EXIT_WRONG_FILE for user nominated files EXIT_NO_ACCESS=62 # environment error: a file (or directory) that should be accessible cannot be accessed due to invalid permissions; use EXIT_BAD_FILE for user nominated files EXIT_BAD_CONFIG=63 # environment error: invalid configuration; config file missing or invalid EXIT_NO_SERVICE=76 # environment error: cannot establish connection to a required service; prefer EXIT_NO_DATABASE for database services EXIT_NO_DATABASE=77 # environment error: cannot establish connection to a required database EXIT_EXHAUSTED=78 # environment error: resources exhausted; out of memory, disk space, inodes, etc EXIT_OFFLINE=79 # environment error: system offline; as configured by administrator EXIT_BAD_PROGRAM=80 # program error: an unhandled and fatal situation encountered EXIT_ERROR=81 # program error: an error caused process termination EXIT_EXCEPTION=82 # program error: an unhandled exception caused process termination EXIT_ASSERT=83 # program error: an assertion violation caused process termination EXIT_TEST_FAILED=84 # program error: test failed; unit-test did not succeed EXIT_INVALID=85 # program error: invalid error level; the programmer nominated an invalid error level and the host exited with 85 instead EXIT_SPECIAL_SUCCESS=90 # special purpose: special operation successful; used for safety (in case improperly invoked) EXIT_OPTIONS_LISTED=98 # special purpose: program options listed; use when programs can be invoked to list their options in a machine readable format EXIT_HELP=99 # special purpose: help or version number requested EXIT_UNIX_BAD_PERMISSION=126 # UNIX: command was found but could not be executed due to permissions EXIT_UNIX_BAD_COMMAND=127 # UNIX: command not found or could not be executed EXIT_TERMINATED_BY_SIGNAL=128 # UNIX: process terminated by signal EXIT_TERMINATED_BY_CTRLC=130 # UNIX: process terminated by Ctrl+C EXIT_GENERIC_1=1 # generic: the generic "some problem occurred" value, prefer something more specific EXIT_GENERIC_2=2 # generic: incorrect usage or invalid arguments, the 404 of error levels EXIT_GENERIC_255=255 # generic: the other generic "some problem occurred" value, prefer something more specific