Resource State Playbook (404 / 410 / ResourceNotFound)

Q: When should I return 410 instead of 404?

Return 410 only when the server knows the resource is intentionally and permanently removed. Use 404 when a current representation is not found and permanence is not asserted.

Q: Why can a resource exist but still return ResourceNotFound or NOT_FOUND?

Most cases are scope mismatch (wrong account/project/region/subscription), stale identifiers, or lifecycle races where callers query before resources are visible in that scope.

Q: Should not-found errors be retried automatically?

Retry only for known transient lifecycle windows (for example post-create propagation). For permanent removals or wrong identifiers, retries will not recover without data or scope correction.

Q: How should deprecated or retired resources expose migration guidance?

Publish deprecation metadata before retirement and keep it available through the full migration window. Send the RFC 8594 `Sunset` header with a clear retirement date on affected responses. Link a canonical replacement resource in response metadata and documentation so clients can switch deterministically. Publish upgrade timelines, examples, and cutover checkpoints before you enforce 410 behavior.

Use this playbook to separate temporary missing-resource lookups from permanent removals, then fix scope, lifecycle, and identifier drift safely.

Last reviewed: February 23, 2026|Editorial standard: source-backed operational guidance

Quick Triage

-Classify semantics first: 404 means current representation is not found, 410 means intentional permanent removal, and provider `ResourceNotFound`/`NOT_FOUND` indicates unresolved resource identity in scope.
-Capture one failing request with resource identifier, scope context (account/project/subscription/region), and lifecycle timeline before changing routes or policies.
-Determine whether the incident is lookup drift (wrong ID/scope), lifecycle race (not yet visible), or confirmed permanent retirement.

Execution Steps

1Reproduce one failing call and preserve request ID, full resource identifier/path, and endpoint scope context.
2Validate identifier correctness and scope alignment first (account/project/subscription/region/tenant/resource group).
3Check creation and visibility lifecycle events for post-create propagation, replication windows, and eventual-consistency delays.
4Check deletion, move, rename, and retirement lifecycle events for permanent-removal intent, redirect signals, and deprecation signals.
5Validate HTTP status policy by using 410 only for intentional permanent removal and using 404 when permanence is unknown or not asserted.
6Confirm cloud resource existence with service-native get/list/describe calls in the same scope before retrying.
7Apply minimal fixes (identifier correction, scope correction, lifecycle-aware redirect or deprecation), then retest valid and invalid lookup paths.

Diagnosis Dimensions

-Protocol semantics: unresolved current representation (404) versus known permanent removal (410).
-Scope correctness: wrong account/project/subscription/region often appears as not-found despite resource existence elsewhere.
-Lifecycle consistency: create/delete timing and eventual-consistency windows can produce transient not-found behavior.
-Deprecation discipline: whether retired resources expose explicit migration path or canonical replacement.

Verify Recovery

-Replay the original failing lookup and confirm valid identifiers now resolve in the intended scope.
-Confirm intentionally retired resources still return the expected permanent-removal behavior where 410 policy applies.
-Observe not-found error rates by endpoint and scope for at least one sustained traffic window after rollout.

What To Avoid

-Retrying blindly on permanently retired resources without checking lifecycle intent.
-Using 410 for transient provisioning delays or replication windows.
-Treating all not-found outcomes as authorization failures without scope and existence verification.
-Hard-coding resource IDs and paths across environments without centralized discovery.

Pro Tip

-Track not-found failures by resource type, scope dimension, and lifecycle phase to separate true deletions from configuration drift quickly.
-Publish deprecation metadata and replacement guidance before switching endpoints/resources to permanent-removal behavior.

Frequently Asked Questions

When should I return 410 instead of 404?

Return 410 only when the server knows the resource is intentionally and permanently removed. Use 404 when a current representation is not found and permanence is not asserted.

Why can a resource exist but still return ResourceNotFound or NOT_FOUND?

Most cases are scope mismatch (wrong account/project/region/subscription), stale identifiers, or lifecycle races where callers query before resources are visible in that scope.

Should not-found errors be retried automatically?

Retry only for known transient lifecycle windows (for example post-create propagation). For permanent removals or wrong identifiers, retries will not recover without data or scope correction.

How should deprecated or retired resources expose migration guidance?

Publish deprecation metadata before retirement and keep it available through the full migration window. Send the RFC 8594 `Sunset` header with a clear retirement date on affected responses. Link a canonical replacement resource in response metadata and documentation so clients can switch deterministically. Publish upgrade timelines, examples, and cutover checkpoints before you enforce 410 behavior.

Official References

Related Error Pages

HTTP 404 HTTP 410 AWS ResourceNotFoundException AZURE ResourceNotFound GCP NOT_FOUND

Quick Triage

-Classify semantics first: 404 means current representation is not found, 410 means intentional permanent removal, and provider `ResourceNotFound`/`NOT_FOUND` indicates unresolved resource identity in scope.

-Capture one failing request with resource identifier, scope context (account/project/subscription/region), and lifecycle timeline before changing routes or policies.

-Determine whether the incident is lookup drift (wrong ID/scope), lifecycle race (not yet visible), or confirmed permanent retirement.

Execution Steps

1Reproduce one failing call and preserve request ID, full resource identifier/path, and endpoint scope context.

2Validate identifier correctness and scope alignment first (account/project/subscription/region/tenant/resource group).

3Check creation and visibility lifecycle events for post-create propagation, replication windows, and eventual-consistency delays.

4Check deletion, move, rename, and retirement lifecycle events for permanent-removal intent, redirect signals, and deprecation signals.

5Validate HTTP status policy by using 410 only for intentional permanent removal and using 404 when permanence is unknown or not asserted.

6Confirm cloud resource existence with service-native get/list/describe calls in the same scope before retrying.

7Apply minimal fixes (identifier correction, scope correction, lifecycle-aware redirect or deprecation), then retest valid and invalid lookup paths.

Diagnosis Dimensions

-Protocol semantics: unresolved current representation (404) versus known permanent removal (410).

-Scope correctness: wrong account/project/subscription/region often appears as not-found despite resource existence elsewhere.

-Lifecycle consistency: create/delete timing and eventual-consistency windows can produce transient not-found behavior.

-Deprecation discipline: whether retired resources expose explicit migration path or canonical replacement.

Verify Recovery

-Replay the original failing lookup and confirm valid identifiers now resolve in the intended scope.

-Confirm intentionally retired resources still return the expected permanent-removal behavior where 410 policy applies.

-Observe not-found error rates by endpoint and scope for at least one sustained traffic window after rollout.

What To Avoid

-Retrying blindly on permanently retired resources without checking lifecycle intent.

-Using 410 for transient provisioning delays or replication windows.

-Treating all not-found outcomes as authorization failures without scope and existence verification.

-Hard-coding resource IDs and paths across environments without centralized discovery.

Frequently Asked Questions

When should I return 410 instead of 404?

Return 410 only when the server knows the resource is intentionally and permanently removed. Use 404 when a current representation is not found and permanence is not asserted.

Why can a resource exist but still return ResourceNotFound or NOT_FOUND?

Most cases are scope mismatch (wrong account/project/region/subscription), stale identifiers, or lifecycle races where callers query before resources are visible in that scope.

Should not-found errors be retried automatically?

Retry only for known transient lifecycle windows (for example post-create propagation). For permanent removals or wrong identifiers, retries will not recover without data or scope correction.