2026-07-10 · 5 min read · Rahul Chitturi
- api
- units
- contracts
Unit bugs are contract bugs. A payload that changes from bytes to megabytes, Celsius to Fahrenheit, or milliseconds to seconds can pass syntax checks while breaking dashboards, limits, billing logic, or alert thresholds.
Before deploy, make each unit visible in the field name, documentation, and example payload. Reviewers should not have to infer whether a value is a count, duration, size, or display-friendly number.
Check the unit at every boundary
The same value may cross database storage, API serialization, frontend display, and analytics export. Each boundary is a chance for a helper to convert once, skip conversion, or convert twice.
- Prefer explicit names such as sizeBytes or durationMs
- Distinguish SI units from binary IEC units for storage and network values
- Verify thresholds and limits use the same unit as the incoming payload
- Keep timestamps separate from durations so seconds and milliseconds do not blur
Make examples part of the review
A written contract is stronger when it includes realistic examples. Add one small value, one boundary value, and one value large enough to expose rounding or display assumptions. Diff those examples when the API changes.
If a migration changes persisted units, plan rollback behavior. Mixed old and new records can make charts look like spikes even when the application logic is correct.
A Flashman workflow
Use the unit converter to confirm expected values, the JSON formatter to inspect payload examples, and the diff tool to review contract changes. Use the timestamp converter when durations and scheduled times appear in the same incident report.
Keep sample payloads local when they include customer usage, billing, or infrastructure metrics. Synthetic values can still prove whether the conversion is correct.