# Conditional API Requests: Use ETags Without Mistaking 304 for Missing Data

<a id="main-content"></a>

AI &amp; Automation

October 28, 2026  ·  7 min read  ·  Victor Valentine Romo

On this page

1. [Keep the Validator Beside the Representation](<#keep-the-validator-beside-the-representation>)
2. [Read Three Synthetic Requests in Order](<#read-three-synthetic-requests-in-order>)
3. [Give Every Cache Entry a Specific Identity](<#give-every-cache-entry-a-specific-identity>)
4. [Choose the Response Branch Before Parsing](<#choose-the-response-branch-before-parsing>)
5. [Recover When the Body Has Disappeared](<#recover-when-the-body-has-disappeared>)
6. [Handle Changed or Absent Validators Deliberately](<#handle-changed-or-absent-validators-deliberately>)
7. [Keep Representation Validation Separate From Sync Progress](<#keep-representation-validation-separate-from-sync-progress>)
8. [Keep GitHub's Quota Rule in Its Own Box](<#keep-github-s-quota-rule-in-its-own-box>)
9. [Sources](<#sources>)

The poll returns no body.

The integration replaces its saved records with an empty list. A report now shows zero open requests, although the source has not changed.

Before parsing a response, decide what its status means for the representation already on disk. A conditional read needs that stored representation to remain useful.

The method below proposes a local storage and review policy. Its endpoint, records, roles, and request trace are fictional. It describes read requests and local draft data only. No account is queried or changed.

<a id="keep-the-validator-beside-the-representation"></a>

## Keep the Validator Beside the Representation

An ETag is an opaque representation validator. Send its saved value in `If-None-Match` for a conditional GET. For an otherwise successful GET, a matching tag yields `304`. A nonmatching tag can yield `200` with content. [RFC 9110, If-None-Match](<https://www.rfc-editor.org/rfc/rfc9110.html#section-13.1.2>).

Think of the validator as the label attached to a retained copy. Keep the copy and its label together. A label without the copy cannot supply the records your report needs.

For the proposed design, give each stored entry a body reference, validator, request identity, and acceptance record. Store the response status and observation time separately. The next reviewer should see [which request produced the accepted body](</articles/data-lineage-small-business-reports/>).

Preserve the validator exactly as received, including quotes and any weak prefix. Do not turn it into a [timestamp](</articles/event-time-processing-time-business-reports/>) or infer a sequence number. RFC 9110 specifies weak comparison for `If-None-Match`. [Validator comparison](<https://www.rfc-editor.org/rfc/rfc9110.html#section-13.1.2>).

The storage rule is an editorial choice: accept the body and validator as one recoverable pair. If writing the body fails, keep the prior accepted pair. Record the failed candidate separately.

This narrows the question raised by [API-first business operations](</articles/api-first-business-operations/>). A connection can work while its local representation handling remains wrong. Review that handling before trusting the report it supplies.

<a id="read-three-synthetic-requests-in-order"></a>

## Read Three Synthetic Requests in Order

Suppose a fictional service exposes a read-only inventory endpoint named `/v1/requests?status=open`. The approved identity can read one synthetic workspace. [The response format is JSON](</articles/http-accept-content-negotiation-business-exports/>).

The first request has no saved validator. It returns three records: R01, R02, and R03. The response carries ETag `"inventory-a"`. The reader validates the shape and stores both the body and validator as entry C1.

The second request uses the same resource, query, representation, and authorization context. It sends `If-None-Match: "inventory-a"`. The response is `304`. C1 remains the body used for the report.

RFC 9110 defines `304` as directing the client to its stored representation. A `304` has no content. It is not a JSON document containing an empty collection. [RFC 9110, 304 Not Modified](<https://www.rfc-editor.org/rfc/rfc9110.html#section-15.4.5>).

The third request sends the same validator. This time the fictional service returns `200`, ETag `"inventory-b"`, and R01 through R04. After local validation, the reader accepts that body and validator as C2.

| Request | Validator sent | Synthetic response | Accepted body afterward | Review result |
| --- | --- | --- | --- | --- |
| One | None | 200, inventory-a, R01 through R03 | C1, three records | Initial representation retained |
| Two | inventory-a | 304, no content | C1, three records | Existing representation revalidated |
| Three | inventory-a | 200, inventory-b, R01 through R04 | C2, four records | Replacement representation accepted |

The table abbreviates validators for readability. The request examples preserve the quoted header values. None of these names represents a real service or production ETag.

The resulting counts are three, three, and four. A zero at the second step would describe the parser's mistake. It would have no supporting collection response.

<a id="give-every-cache-entry-a-specific-identity"></a>

## Give Every Cache Entry a Specific Identity

For this worksheet, define the cache identity before storing a response. Include the resource path, query parameters, requested representation, API version, and authorization context.

A request for open records differs from a request for closed records. Page one differs from page two. A request for selected fields differs from a request for the full supported representation.

Use a stable internal reference for [the authorized account](</articles/service-account-inventory-small-team/>), workspace, and permission boundary. Keep credentials outside the key and outside ordinary logs. Never share private cached content across identities.

These are proposed isolation rules for the local reader. They are not a complete implementation of HTTP caching. Endpoint documentation and response cache controls still govern whether and how a response may be stored.

When an identity or permission boundary changes, mark the old entry ineligible for reuse. Require a fresh [access review](</articles/small-team-access-review-evidence/>) and an approved read. A body left on disk does not establish current permission to show it.

Avoid a single global variable named “last ETag.” Put the validator under the same entry identity as its accepted body. The next request should retrieve a pair selected by that identity.

Record the configuration version with the entry. If a maintainer changes the field selection, the reviewer can then distinguish an intentional new request from a broken old lookup.

<a id="choose-the-response-branch-before-parsing"></a>

## Choose the Response Branch Before Parsing

Use the [decision table](</articles/business-decision-table-gaps-overlaps/>) as a review aid. Its actions are the proposed local policy. Match the actual implementation to the endpoint contract before adopting it.

| Observed result | Local prerequisite | Proposed action | Output state |
| --- | --- | --- | --- |
| 200 with valid expected content | Request identity is correct | Retain and validate candidate; accept body and current validator together | Fresh representation accepted |
| 304 | Eligible matching body exists | Reuse accepted body; record this validation attempt | Existing representation revalidated |
| 304 | Matching body is missing or unreadable | Mark incomplete; arrange a bounded unconditional recovery read | No new usable result |
| 200 without an ETag | Content passes acceptance | Store accepted body without a conditional validator | Ordinary read accepted |
| Provider error or transport failure | Any cache state | Preserve accepted data with an explicit freshness limitation | Current read incomplete |
| Unexpected status or invalid content | Any cache state | Hold candidate and assign review | Current read unresolved |

Do not send every response through the same JSON parser and then recover from whatever exception appears. Select the status branch first. Parse content only where the branch expects it.

For a `200`, validate the expected body rather than [treating the status alone as acceptance](</articles/api-content-type-response-validation/>). A fictional response containing the wrong workspace must remain rejected even if its JSON is valid.

If a valid accepted `200` contains zero records, the proposed policy can accept zero. That result comes from inspected content. Preserve the response reference so the reviewer can [distinguish it from missing content](</articles/null-blank-zero-business-data/>).

<a id="recover-when-the-body-has-disappeared"></a>

## Recover When the Body Has Disappeared

Change the synthetic example. The local body file C1 is missing, but its validator survives in a separate settings record. A conditional request returns `304`.

The reader now lacks a usable representation. Mark the attempt incomplete. Do not reconstruct the missing records from a count, a previous screenshot, or another workspace's cache.

Under the proposed recovery policy, retire the orphaned validator from active use. Keep its diagnostic reference. Plan an unconditional GET under the same approved request identity, subject to the provider's waiting rules and the run's deadline.

A successful recovery still needs body validation and durable storage. A failed recovery leaves the attempt incomplete. Put the owner and next review condition in the receipt.

If the job prepares a report, identify whether an older accepted report remains available. Label its source time explicitly. Do not describe a missing source representation as a fresh report with no records.

This is a useful [handover](</articles/operations-handover-small-team/>) exercise. Give a receiver a synthetic orphaned validator and ask which state remains accepted. The answer should identify the missing body before proposing another request.

<a id="handle-changed-or-absent-validators-deliberately"></a>

## Handle Changed or Absent Validators Deliberately

In the third synthetic request, the new body and new validator arrive together. Stage them as one candidate. Review the candidate before replacing the accepted entry.

If the candidate body cannot be retained, leave C1 accepted with its earlier observation. Do not save `"inventory-b"` as the validator for C1. That pair would claim a relationship the reader never established.

If an accepted response has no ETag, remove any old ETag from that active entry under this policy. Otherwise a later request could attach an earlier validator to a different body.

When the endpoint supplies no supported validator, use ordinary reads according to its documented schedule. Record that conditional validation is unavailable. Do not manufacture an ETag from a local hash and send it as a provider validator.

A local hash can help [identify a retained file](</articles/checksum-verification-business-file-handoffs/>) within your own acceptance process. Keep that purpose separate from any header the server recognizes. Label each field by the claim it supports.

For scheduled [polling](</articles/asynchronous-api-export-job-tracking/>), define the business appointment independently. The [time zone and daylight-saving worksheet](</articles/automation-time-zones-daylight-saving/>) explains why a daily label needs a clock and an interval.

<a id="keep-representation-validation-separate-from-sync-progress"></a>

## Keep Representation Validation Separate From Sync Progress

The response table concerns one selected representation. The proposed acceptance record should make no broader claim about traversal, history, or changes across other resources.

In the fictional inventory, a retained body can support the count displayed from that body. It cannot by itself prove that [every required collection page was read](</articles/api-pagination-business-export-completeness/>) or every destination record was applied.

If the broader workflow tracks a synchronization [checkpoint](</articles/incremental-api-sync-checkpoint-safety/>), retain its existing acceptance rule. Neither a provider error nor an unresolved local body permits advancing that checkpoint.

Record a separate validation time for a successful conditional read. Preserve the original body retrieval time as well. Those timestamps answer different questions during review.

For a multi-request job, leave collection status incomplete until its own completion evidence exists. One unchanged page should not turn an interrupted sequence into a finished export.

After an interruption, use the workflow's [catchup and backfill policy](</articles/missed-scheduled-jobs-catchup-backfill/>) to decide which work remains necessary. Repeated polling alone does not define the recovery boundary.

<a id="keep-github-s-quota-rule-in-its-own-box"></a>

## Keep GitHub's Quota Rule in Its Own Box

GitHub documents a specific benefit: a correctly authorized conditional request returning `304` does not count against its primary [rate limit](</articles/api-rate-limits-retry-budget/>). The documentation requires an `Authorization` header. [GitHub REST API best practices](<https://docs.github.com/en/rest/using-the-rest-api/best-practices-for-using-the-rest-api#use-conditional-requests>).

Apply that statement to GitHub REST API usage covered by the cited guidance. Do not extend it to every provider, every response status, or every kind of limit.

For another service, leave quota treatment unknown until its documentation establishes it. Keep the source and checked date in the runbook. The local response-state policy can stand without an assumed quota discount.

Before handover, inspect one accepted pair, one unchanged-read receipt, and one failed-read receipt. Each should identify the same request boundary without revealing credentials. Ask the receiver which body a report would use.

Keep the saved representation attached.

<a id="sources"></a>

## Sources

- [RFC 9110, section 13.1.2: If-None-Match](<https://www.rfc-editor.org/rfc/rfc9110.html#section-13.1.2>). Conditional GET and validator comparison. Checked 2026.10.28.
- [RFC 9110, section 15.4.5: 304 Not Modified](<https://www.rfc-editor.org/rfc/rfc9110.html#section-15.4.5>). Stored representation and absence of response content. Checked 2026.10.28.
- [GitHub Docs: Best practices for using the REST API](<https://docs.github.com/en/rest/using-the-rest-api/best-practices-for-using-the-rest-api>). GitHub-specific authorized conditional-read quota treatment. Checked 2026.10.28.
