ID Structures: What's in a Name?

When building applications, mostly people think about entity IDs. Usually they are intentionally opaque: nobody wants users seeing auto-incrementing integers that reveal how many customers you have. Others, like ULIDs, trade away some opacity for sortability.

What about human-facing codes, ones users actually see and may need to share? Nobody thinks ahead about those.

Codes Are Everywhere

Think about all the places you need stable, human-friendly identifiers:

• Error codes: RB2042: Invalid configuration gives your support team something to grep for and your users something to Google.
• Discount codes: Marketing promo codes like SUMMER25 need to be flexible, but internally you want something that’s stable and could have many codes linked to it.
• Product SKUs: Warehouse staff, customer service reps, and sales teams all need something they can read over the phone without wanting to die.
• Feature flags: FF0042 beats enable_new_checkout_flow_v2_final_REAL when you’re debugging.
• Ticket IDs: Jira and other task trackers use CT-0042 for tickets. The title can change as things become more clear, but commits, branches, and pull requests can be linked by the stable ID.

The pattern is the same: you need an identifier that’s stable, greppable, and doesn’t make humans sad.

My Favorite Format

I like a simple convention: a two-letter uppercase prefix followed by a four-digit number like TX6767. When a dev sees a log for RB2042, you can grep your codebase and land on the exact line that threw it. Avoid reusing codes in multiple places, unique codes are the easiest to search and maintain over time.

Users can paste the code into your docs search and find the relevant KB article. You can even put the code in the title of the article. Error messages change. “Invalid input” becomes “The provided value must be a positive integer.” But RB2042 stays RB2042 forever. StackOverflow answers from years ago will come right up.

The two-letter prefix gives you enough namespace to organize. Maybe RB is your rules engine, TX is the payment processor, ID is the auth system. The letters could also be arbitrary. The point is with 2 letters and 4 digits there are 6.76 million available codes. For anything created at human scale that’s plenty.

Tracking Codes Long-Term

The best part is that the convention can be low-tech. Track it in a README.md in the project repo, a wiki, or a spreadsheet. Any of these allow you to track codes that are taken, add notes, and avoid duplicates. Wherever you choose, make sure there is only one place and that it’s linked from your other docs.

The best though is to keep them in code. A module or file in an existing project is fine, or a DB for things like promo codes that change outside the SDLC.

The http-errors package gives you the semantic values like new createError.NotFound(). Do the same thing for your codes, it doesn’t have to be a class. Create a module that exports your codes as constants with descriptive names:

# errors.py
INVALID_CONFIG = 'RB2042'
AUTH_TOKEN_EXPIRED = 'AU0017'
PAYMENT_DECLINED = 'TX0103'

# or a static class to include other attributes
class InvalidConfig:
    code = 'RB2042'
    message = 'Invalid configuration'
    status = 400

Now you get a single source of truth and a versioned package for adding new codes. Adding a new code? You’ll see immediately if the number is taken.

The real trick isn’t the format or the tracking system. It’s the discipline of maintaining the codes over time. Pick a convention with your team and make it a code review checkpoint.