Error Codes Enum

title: "Error Codes Enum — Machine-Readable Error Identification" description: "API error code enums provide machine-readable identifiers for each error type, enabling clients to handle specific errors programmatically with precision." date: 2026-06-28 lastmod: 2026-06-28 weight: 25 tags: [apis, error-handling] }

Error code enums are machine-readable string identifiers for each API error type, enabling client code to handle specific error conditions without parsing human-readable messages.

What You'll Learn

• Designing error code enums
• Error code namespacing and hierarchy
• Documenting error codes

Why It Matters

Human-readable messages change; error codes don't. Clients that rely on error codes are more robust than those parsing message text.

Code Examples

# Error code enum
from enum import Enum

class ErrorCode(str, Enum):
    # Authentication errors
    AUTH_REQUIRED = "AUTH_REQUIRED"
    INVALID_TOKEN = "INVALID_TOKEN"
    TOKEN_EXPIRED = "TOKEN_EXPIRED"
    INVALID_API_KEY = "INVALID_API_KEY"

    # Authorization errors
    FORBIDDEN = "FORBIDDEN"
    INSUFFICIENT_SCOPE = "INSUFFICIENT_SCOPE"

    # Validation errors
    VALIDATION_ERROR = "VALIDATION_ERROR"
    MISSING_FIELD = "MISSING_FIELD"
    INVALID_FORMAT = "INVALID_FORMAT"
    INVALID_VALUE = "INVALID_VALUE"

    # Resource errors
    NOT_FOUND = "NOT_FOUND"
    CONFLICT = "CONFLICT"
    DUPLICATE_RESOURCE = "DUPLICATE_RESOURCE"
    RATE_LIMIT_EXCEEDED = "RATE_LIMIT_EXCEEDED"

    # Server errors
    INTERNAL_ERROR = "INTERNAL_ERROR"
    SERVICE_UNAVAILABLE = "SERVICE_UNAVAILABLE"
    UPSTREAM_ERROR = "UPSTREAM_ERROR"

    def http_status(self):
        mapping = {
            "AUTH_": 401,
            "FORBIDDEN": 403, "INSUFFICIENT_SCOPE": 403,
            "NOT_FOUND": 404,
            "CONFLICT": 409, "DUPLICATE_RESOURCE": 409,
            "RATE_LIMIT_": 429,
            "INTERNAL_": 500, "SERVICE_": 503, "UPSTREAM_": 502,
        }
        for prefix, status in mapping.items():
            if self.value.startswith(prefix):
                return status
        return 400

// Error code constants
const ErrorCodes = {
  AUTH_REQUIRED: 'AUTH_REQUIRED',
  INVALID_TOKEN: 'INVALID_TOKEN',
  TOKEN_EXPIRED: 'TOKEN_EXPIRED',
  VALIDATION_ERROR: 'VALIDATION_ERROR',
  NOT_FOUND: 'NOT_FOUND',
  CONFLICT: 'CONFLICT',
  RATE_LIMIT_EXCEEDED: 'RATE_LIMIT_EXCEEDED',
  INTERNAL_ERROR: 'INTERNAL_ERROR'
};

// Client-side error handling
function handleApiError(error) {
  switch (error.code) {
    case ErrorCodes.TOKEN_EXPIRED:
      return refreshToken();
    case ErrorCodes.RATE_LIMIT_EXCEEDED:
      return waitAndRetry(error.retryAfter);
    case ErrorCodes.VALIDATION_ERROR:
      return showFieldErrors(error.fields);
    default:
      return showGenericError();
  }
}

Common Mistakes

1. Using HTTP Status Codes as Error Codes

Status codes are too coarse. VALIDATION_ERROR is more specific than just 400.

2. Inconsistent Naming

Mix of snake_case, camelCase, and UPPER_CASE in error codes.

3. No Documentation for Each Code

Document what each error code means and when it's returned.

4. Overly Specific Error Codes

Too many error codes are hard to maintain. Group related errors.

5. Breaking Error Code Contracts

Error codes are part of your API contract. Never change existing codes.

Practice Questions

1. Why are error codes better than parsing error messages?
2. What naming convention works well for error codes?
3. How do you group related error codes?
4. Should error codes be versioned?
5. How do clients use error codes effectively?

Answers:

1. Error codes are stable identifiers; messages can change.
2. UPPER_SNAKE_CASE with category prefixes (AUTH_INVALID_TOKEN).
3. Use consistent prefixes: AUTH_, VALIDATION_, RESOURCE_, SERVER_.
4. Yes. Error codes are part of the API contract. Add new codes, don't change existing ones.
5. Using switch statements or lookup tables to handle specific errors.

Challenge: Design a complete error code enum for a payment API covering auth, validation, resource, business logic, and server errors. Include at least 20 error codes.

FAQ