Error Categories and Codes

Error names and codes offer a standardized way to classify and report errors that occur while parsing a document. Every parser must support the predefined error categories. However, the implementation details—such as the specific names or casing—can be adjusted to align with the conventions of the programming language being used.

Here’s how you might define these error categories in different programming languages:

enum class Error : uint8_t {
    Io = 1,
    Encoding = 2,
    // ...
};

class Error(enum.StrEnum):
    IO = "io"
    ENCODING = "encoding"
    # ...

#define ERR_IO 1
#define ERR_ENCODING 2
/* ... */

Rules for Error Reporting

1. A parser must use the predefined error categories.

2. A parser must use the name of the error category, adapting it as needed for the target language.

3. A parser must provide a method to convert the error category to a case-insensitive string matching the error name.

4. If a parser assigns an integer code to an error category, it must use the predefined code from the “code” field.

5. A parser must report the line number if the error is related to a specific line in the document.

6. A parser should report the column number of the error when possible.

7. A parser should include additional context or details about the error whenever feasible.

8. A parser can define extra subcategories for each error to offer more specific details.

9. A parser can create additional categories starting at code 100. Codes 1–99 are reserved for errors defined by the language specification.

List of Error Codes

Code	Name	Description
1	IO	Input/Output error: A problem occurred while reading data from an I/O stream.
2	Encoding	Invalid encoding: The document contains a problem with UTF-8 encoding.
3	UnexpectedEnd	Unexpected end of document: The document ended unexpectedly.
4	Character	Disallowed character: The document contains a control character that is not allowed.
5	Syntax	Syntax error: The document has a syntax error.
6	LimitExceeded	Limit exceeded: The size of a name, text, or buffer exceeds the permitted limit.
7	NameConflict	Name conflict: The same name has already been defined earlier in the document.
8	Indentation	Indentation mismatch: The indentation of a continued line does not match the previous line.
9	Unsupported	Unsupported feature version: The requested feature/version is not supported by this parser.
10	Signature	Signature rejected: The document’s signature was rejected.
11	Access	Access denied: The document was rejected due to an access check.
12	Validation	Validation failure: The document did not meet one of the validation rules.
99	Internal	Internal error: The parser encountered an unexpected internal error.
100+	Implementor Defined	Implementors can define additional error categories, starting with code 100.

Note

The Internal error should be reserved as a last-resort indicator for serious issues, such as missing runtime data required by the parser.

Available Data

The data directory contains the error-codes.json file, which defines all error categories in a machine-readable format.