CLOUD INFRASTRUCTURE

Aurora Data API Responses Exceeding 1 MiB Cause Admin 502 Errors: Our Reproduction and Chunked-Read Fix

Login succeeds, but the list still returns 502? We measured actual byte counts to identify the Data API limit, preserved complete audit records through chunked reads and a consistent snapshot, and provide a reusable testing method.

A real incident exposed the limits of pagination by a fixed record count: even 20 records can exceed the transfer limit. This article presents the measurement methodology, an implementation using 8192-character chunks, a two-part cursor, and a transaction snapshot, plus integrity checks and production validation results.

Why Does the Research List Still Return 502 After a Successful Login?

On September 14, 2026, login to the Aperture admin interface succeeded, but the research list endpoint returned 502, and the page reported that data had failed to load. Of the ten initialization requests, the research list request was the one that failed; the previously fixed statistics endpoint was working normally. This distinction matters: account authentication and research queries follow different paths, and logging in again cannot resolve a query response that exceeds the size limit.[S1]

Production logs traced the problem to the research list query and Aurora Data API's response size limit. The query JSON for the 20 most recent complete research records totaled 1,094,895 bytes, with growing audit data for database-wide deduplication increasing the size of individual records. At the time of the failure, the amount of data transferred could continue to grow even without an increase in the number of list entries.[S1]

This article reviews that incident, with code and tests pinned to the repository version publicly available on September 14. We do not treat latency measurements from a single fix as a performance guarantee for other environments, nor do we attribute all backend 502 errors to the Data API. Diagnosis should still begin with the specific failed request and its upstream error.

A Limited Row Count Does Not Mean a Limited Byte Count

AWS documentation specifies a 1 MiB result-set limit for the error Database response exceeded size limit. One MiB equals 1,048,576 bytes, and our query JSON at the time exceeded that amount. This byte count was a measurement of the query result, not the size of the browser page or the length of a single article's body.[S1][S4]

AWS recommends keeping the data returned by each Data API call within the limit, using multiple ExecuteStatement calls with LIMIT to retrieve results when necessary. Ordinary row-based pagination can reduce responses for many lists, but if a row contains a large audit JSON value, even LIMIT 1 cannot guarantee that a single response stays within the limit. AWS also separately documents a 64 KB per-row limit, so both the individual row size and the total response size must be considered.[S4]

We needed to preserve the deduplication evidence in full; simply truncating audit fields would prevent the admin interface from showing the complete basis for a decision. The final approach serializes query rows as JSON, splits them into character-based chunks, reads a small number of chunks at a time, and reconstructs the original records in order at the application layer. The list still returns the 20 most recent complete research records.[S1][S2]

Measure the Problem in an Isolated Database, Then Validate the Read Strategy

The following SQL is a minimal example for reproducing an oversized logical field and can be run in an isolated PostgreSQL database. The content generated by repeat is only test data; local PostgreSQL can handle this field. The SQL itself does not simulate the cloud Data API gateway or automatically produce a 502 locally. To reproduce the transfer error, an actual Data API call must return this field.[S3][S4]

SELECT octet_length(repeat('x', 1100000)) AS payload_bytes;
SELECT repeat('x', 1100000) AS oversized_payload;

Combine Record Ordering with a Chunk Cursor

The read_research_rows implementation first serializes each row using row_to_json(source)::text, then assigns row_no using a stable sort. Each row is split into 8192-character chunks, with at most 8 chunks fetched per call. The outer cursor stores both row_no and chunk_no, continuing from the chunk after the last one returned. Tracking only the row number would miss subsequent chunks in the same row, while tracking only the chunk number would not distinguish between rows.[S2]

The caller must supply a trusted query and a unique, stable sort key. The research list uses time and ID to determine the order, avoiding indeterminate record positions when timestamps are identical. The application concatenates the fragments of each row in sequence, then parses the complete JSON. On the final page, it must also add the last row, which has not yet been emitted, to the results.[S1][S2]

8192 is a character count, not a guarantee that each chunk is only 8192 bytes. Chinese characters, emoji, and escaping affect the actual encoded size. We used a conservative chunk size and number of chunks per page to leave headroom, and included these inputs in the tests. Production use still requires checking serialization overhead, service limits, and future field changes.[S2][S3]

Multiple Reads Require the Same Database Snapshot

After a single response is split across multiple queries, new research records written between queries can change the row order, or even cause successive fragments to come from different versions. PostgreSQL's Repeatable Read provides a consistent snapshot for reads within a transaction. We placed the list, detail, and associated evidence reads in the same read-only, repeatable-read transaction.[S1][S5]

The read function does not start or end transactions itself; the caller is responsible for transaction boundaries. The Psycopg documentation explains that database operations start a transaction by default, and that a connection context commits on normal exit and rolls back on an exception. Transaction isolation must therefore be configured at the correct point: you cannot run a query first and then assume that a later isolation setting can change the snapshot already read.[S2][S6]

The following example shows the call pattern. conn must be a connection dedicated to this request, with no other queries executed yet. Both order_by and the SQL come from application code; user input must not be interpolated directly into either parameter.[S2]

from backend.research import read_research_rows

conn.execute('SET TRANSACTION ISOLATION LEVEL REPEATABLE READ, READ ONLY')
rows = read_research_rows(
    conn,
    'SELECT id, summary FROM research_runs ORDER BY id DESC LIMIT 20',
    order_by='id DESC',
)

Verifying Integrity Is More Useful Than Checking Status Codes Alone

Our regression tests cover four groups of boundary cases: the old query result exceeds the size limit; the latest 20 records remain complete and stably ordered; a single oversized audit record and Chinese characters, emoji, quotation marks, and newlines in the evidence are reconstructed accurately; and empty lists, missing detail records, and concurrent writes during reads behave as expected.[S1][S3]

The tests use a real PostgreSQL database and check result sizes through a test connection wrapper. They can detect missing data and inconsistencies in reads, but cannot replace production gateway validation. After deployment, we separately used a browser to verify login, ten initialization requests, seven admin views, three research detail views, recovery after a refresh, and logout.[S1][S3]

Running the repository tests requires installing the project dependencies and preparing an isolated PostgreSQL database in which test schemas can be created and deleted. The tests clean up their own schemas. Do not point the connection variable below at production; users must fill in the connection address according to their local configuration.[S3]

RESEARCH_TEST_DATABASE_URL='postgresql://USER:PASSWORD@127.0.0.1:55432/TEST_DATABASE' \
  .venv/bin/python scripts/test_admin_research.py -v

Fix Results and Limits of Applicability

After this fix, the production database read returned 20 complete research records. The complete application-layer list was 1,337,245 bytes, and a direct measurement took approximately 1.65 seconds; all ten initialization endpoints returned 200 in the browser. This application-layer list size and the query JSON size at the time of the failure were measured at different stages and from different snapshots. Dividing one by the other cannot establish a compression ratio or performance improvement.[S1]

Chunking addresses the limit on a single transfer; it does not eliminate the network and parsing costs of large fields. As data continues to grow, repeated serialization queries may also increase database load. If list users need only summaries, a separate design could load details on demand. Whether to change the interaction should be determined by product requirements; fields must not be silently discarded when users need audit evidence.

For similar failures, the troubleshooting sequence can be standardized: identify the failed endpoint and upstream error, measure the actual response size, distinguish per-row limits from total-response limits, choose pagination or chunking, and then verify integrity, consistency, and production behavior. Apply this approach to another system only when the evidence supports it.

Keep following engineering practices

Subscribe to new articles with an RSS reader, or share this article with someone working on similar problems.

Subscribe to RSS updates