1) Numeric vs. Descriptive error codes

• Numeric error codes
  • Pros
    • Numbers can be compared mathematical (e.g. x >= 500 && x < 600) 
    • We can have reserved spaces for different purposes (e.g., engine, persistence, custom)
  • Cons
    • Not very human-readable
• Descriptive error codes (e.g., “DEADLOCK”)
  • Pros
    • Human and machine-readable
  • Cons
    • Pattern matching is more complex when bringing in differentiators for built-in and custom error codes
    • Generic codes that are a meaningful fit for any use case might be hard to find
    • Categories might be hard to achieve with an all too simple error code format like "DEADLOCK"

2) Categories

• Different layer, different range?
• A user can define custom error codes, but the differentiation between built-in or custom error codes is bad
• When adding more built-in error codes in the future, they might override the custom ones => a reserved namespace for built-in vs. custom codes makes lots of sense

3) Real-life examples

• Standardized REST API error handling and generalized error-handling schema: https://tools.ietf.org/html/rfc7807
  • “type – a URI identifier that categorizes the error”
  • It might work well for an application that cannot be extended, but what would the URI look like for user-specific custom errors?
  • Twitter API 2.0 uses it: "type": "https://api.twitter.com/2/problems/client-forbidden"
• Facebook Graph API uses type and code
  • Type: exception type like OAuthException
  • Code: numeric code
  • Have categories: e.g., 200-299 => permission problems, > 400 => authentication problems

4) Additional Provide Direct Link

Is a direct link to our docs and the error code description a good idea?

"help": "https://example.com/help/error/auth-0001"

Discussion

• Numeric error codes are more powerful compared to descriptive error codes
• We should introduce coarse-grained categories to have reserved spaces between built-in and custom error codes so that they don't conflict with each other
  • When we add more error codes in the future, we can think if we want to have more categories within the coarse-grained categories (e.g., subcategory authorization)
• RFC7807 makes proposals that might be useful in some situations, however, URI identifiers for errors have multiple downsides in our specific case:
  • When we change the URL of our documentation, we need to take care to add redirects to maintain the functionality of the URLs
    • This is also true for providing an additional direct link to our documentation
    • A direct link is nice-to-have especially when discovering the feature for the first time; as soon as you got used to the feature, you know where in our documentation you need to look up the error codes
  • When a user adds custom error codes, they might not have external documentation
  • We cannot benefit from the advantages of numeric error codes

Decision

Opting for:

• Numeric error codes
• Coarse-grained categories with enough space to add subcategories in the future