Edge Case Checklist Before Coding
Most post-release defects happen outside the happy path. Edge-case planning is the cheapest way to reduce incidents before code review and QA cycles begin.
Quick answer
A complete edge-case list covers invalid input, duplicates, boundary limits, concurrency, permissions, timeout behavior, and rollback safety. Use it during spec review — not after implementation.
Core edge-case categories
- Input validation: null, empty, malformed, or out-of-range values.
- Data uniqueness: duplicate submissions and idempotent retries.
- Boundary constraints: max length, max count, pagination edges.
- Race conditions: concurrent updates and stale-read decisions.
- Authorization: role-specific visibility and action limits.
- Dependency failure: timeout, retry, circuit-breaker behavior.
Edge-case matrix example
# Edge Case Matrix: Order Create Flow - request body missing customerId expected: 400 validation error, no DB insert - same idempotencyKey repeated expected: return original 201 response body - concurrent stock reservation on last inventory item expected: one success, one 409 conflict - user role = viewer tries create action expected: 403 forbidden, audit log entry - payment provider timeout expected: retry with backoff, eventual failure -> 503 with traceId
Review questions for teams
- Which edge cases are explicitly accepted as out-of-scope?
- What behavior is expected under duplicate or retried requests?
- Are conflicting writes deterministic and testable?
- Can monitoring detect these failure modes in production?
If the team cannot answer these questions before coding, the risk has been deferred, not removed.
Definition of done for edge-case coverage
- Each high-risk edge case has a mapped test case.
- Expected behavior is documented for retries and partial failures.
- Rollout has alerts for edge-case regressions.
- Rollback does not create inconsistent data states.
High-risk domain examples
The order-create matrix above shows the pattern. These domain-specific examples cover three areas where edge cases are most costly when discovered late: payment processing, authentication, and file ingestion.
# Payment processing edge cases - amount = 0.00 -> reject with validation error, no gateway call - currency mismatch between cart and card -> 400, no charge - gateway timeout after charge initiated -> record ambiguous state, trigger reconciliation job, return 503 with retryable flag - duplicate payment attempt within 10s -> return original receipt, no second charge # Authentication edge cases - expired token used after 1ms grace window -> 401, not 403 - valid token for deactivated account -> 403 with account_suspended code - simultaneous login from 3 sessions -> oldest session invalidated, new session issued, audit log records all three events - password reset link reuse after first click -> 410 Gone # File upload edge cases - file size exactly at limit (10MB) -> accepted - file size at limit + 1 byte -> 413 with clear size message - file type spoofed (PDF extension, executable content) -> rejected by content inspection, not extension check - upload interrupted mid-transfer -> partial file discarded, no record created
Payment edge cases that reach production typically result in double charges or unreconciled transactions — both expensive to reverse. Authentication edge cases that are undocumented produce inconsistent security behavior that is invisible until a breach audit. File edge cases are the most common source of security vulnerabilities when content inspection is absent.
How to prioritize: risk × discoverability
Not every edge case requires the same level of spec detail. A practical prioritization uses two axes: the consequence if the case goes wrong (risk), and how easily QA or monitoring would detect it in production (discoverability). High risk combined with low discoverability requires an explicit spec entry and a mapped test case before implementation begins.
| Low discoverability | High discoverability | |
|---|---|---|
| High risk | Document and test before coding: payment conflicts, concurrent writes, permission boundary failures, data corruption paths. | Document and add monitoring: performance degradation, third-party outages, schema validation failures. |
| Low risk | Document as out-of-scope with rationale: cosmetic rendering edge cases, non-default locale formatting. | Note but do not block: minor validation errors with clear user messaging. |
The output of this prioritization is not a complete list of every possible edge case — that is impossible and counterproductive. It is a prioritized list that the team agrees on before coding, with each item classified by who owns the test case and when it must be resolved.
Edge cases across system layers
Edge cases cluster differently depending on the layer of the system they affect. A single user action can expose distinct edge cases at the API layer, the service layer, the database layer, and the background job layer simultaneously. The spec should identify which layer each edge case lives in, so the correct engineer owns the test.
At the API layer, watch for malformed request bodies, missing required headers, oversized payloads, and unexpected content types. At the service layer, the common cases are dependency unavailability, circuit-breaker state, retry storm behavior, and cache invalidation timing. At the database layer, look for unique constraint violations, foreign key failures on delete, transaction isolation level effects, and migration rollback impact on existing data. At the background job layer, consider job queue backup under load, duplicate execution from failed acknowledgment, poison message handling, and dead-letter queue behavior.
A common gap is edge cases at the job layer. Because jobs run asynchronously, their failures are invisible to the user at request time — which is exactly why they need explicit spec coverage. An undocumented job failure mode that silently drops records is more damaging than a synchronous error that a user can retry.
Use these templates
Related articles
Editorial note
This guide covers Edge Case Checklist Before Coding for spec-first engineering teams. Examples are illustrative scenarios, not production code.
- Author details: Daniel Marsh
- Editorial policy: How we review and update articles
- Corrections: Contact the editor