Skip to content
FmtTools

Workflow toolkit

Tools for Debugging HTTP APIs

What to do when a response arrives as one unreadable line: check the encoding claims first, decode honestly, and name the step you are stuck on.

Updated
November 17, 2026
Reading time
18 min read
Length
3,650 words
Reviewer note
Checked against the published specification
A debugging runbook laid out in six panels: a single long response line, the three encoding headers, a token split into three segments, a paginated array, two payloads being compared and a query string with escaped characters.

The failure is almost never that you cannot parse JSON. It is that the bytes you are holding are not the bytes the server sent, or are perfectly valid and mean something other than what the field name implies. This page is a runbook for the distinct problems hiding behind "the response is unreadable", with a place to start for each one.

Triage

When the response arrives unreadable

A list endpoint returns 2 MB with no indentation, and your editor has stopped responding. Resist the instinct to pretty-print it first. Formatting a document you do not yet understand turns a triage problem into a scrolling problem. The useful first move is structural: paste the body into the JSON Validator and read the counts before the content — byte count, line count, root kind, nesting depth, member and value counts, the largest array at any depth, and a structure outline of the first object and first array element. Those numbers answer the three questions that determine what you do next: is this one document or several, where is the collection buried, and did the whole body arrive.

Truncation is the single most common cause of a large body that will not parse, and it has three distinct shapes that look identical from the terminal:

the three truncation shapes3 lines
{"items":[{"id":1,"body":"lorem…   <- cut mid-string, no closing braces
{"items":[{"id":1},{"id":2"}               <- cut mid-token: expected a "," or "}"
{"items":[{"id":1}]}x                     <- one paste too far: extra closing bracket

Same error message in your console, three different causes. Byte count against Content-Length separates them.

The three encodings, and the order you undo them

A response that looks like garbage is far more often a failed undo of one of three transformations than a server producing garbage. Three headers describe three different layers, and you must undo them in order:

The three transformations, in the order you must undo them
LayerHeaderWhat it wrapsHow to undo it
1. FramingTransfer-Encoding: chunkedThe HTTP/1.1 message content, for safe transportRead hex-length chunk prefixes until a zero-length chunk
2. CodingContent-Encoding: gzip, br, zstdThe representation data itselfDecompress, left to right in the header value
3. CharacterContent-Type charset parameterThe characters inside the decoded bytesDecode UTF-8, not latin-1, not twice

RFC 9112 §7 calls framing a transformation for safe transport; RFC 9110 §8.4 calls content coding a property of the representation. Framing bytes are never your data.

The rule is: de-chunk, decompress, decode characters, parse. Most "the server sent broken JSON" reports against a compressed endpoint are one step of that chain skipped or reversed. A hex preview beginning 1f 8b under a header saying application/json means the coding step is still pending, not that the payload is corrupt. Two version-sensitive facts: HTTP/2 and HTTP/3 forbid Transfer-Encoding entirely, so the same endpoint can arrive chunked through one proxy and unchunked through another; and Content-Length describes the encoded data, so its disagreeing with your decompressed byte count is not a bug.

Mangled text is a decoding mistake, not a server bug

Curly quotes becoming three characters, an umlaut becoming a letter plus an accent, a name becoming Smithe?? — none of those are produced by a server. They are produced by a decoder that was handed UTF-8 bytes and asked to interpret them as a single-byte code page. RFC 8259 §8.1 requires text exchanged between systems to be encoded in UTF-8, so application/json; charset=windows-1252 is a document that breaks the interoperability clause, not a client that needs a different decoder.

Symptom, mechanism, and the check that proves it
What you seeWhat happenedHow to prove itCorrect fix
 and é in place of curly quotesUTF-8 bytes decoded as Windows-1252Count bytes against characters in the decoded textDecode as UTF-8; do not re-encode
Smithe?? or boxesEncoder could not represent the character and substitutedCompare the source value, not the renderingRe-export from the system that still has the data
The first header name has an invisible prefixA BOM was read as part of the stringA utf8-bom warning at offset 0Strip the mark before ingesting
Emoji arrive as pairs of boxesText was handled as 16-bit units, not code pointsA lone-surrogate warning from the validatorEscape as a surrogate pair, or fix the encoder

Every row is a decoder decision. Not one of them is fixed by editing the text.

The expensive version of this mistake is silent. A name that differs from the reference table by one decomposed combining character does not look mangled, it looks like a missing record, and the next engineer responds by adding an outer join. Character problems are only cosmetic when the text is displayed; as soon as the text is a key, a mismatch is a data loss event with a cosmetic symptom.

The body you cannot read is not JSON

Before you debug a parser, check whether the payload was ever a JSON document. A large share of unreadable API responses are HTML, XML, an error page from something in the middle, or a different media type wearing a JSON file extension. The practical check is a magic-byte look: a payload whose first printable byte is < is XML or HTML; one that starts with an opening brace and a double quote is JSON. The Base64 decoder compares leading bytes against a signature table and names the container it found — a gzip stream, a ZIP archive, a PDF — which holds even when the declared type or file extension is wrong.

Common non-JSON bodies and what produced them
First charactersWhat it isWho produced itWhere the real error is
<!DOCTYPE htmlA browser-facing error pageAn origin server or framework default error handlerAccept was wrong, or the route does not exist
<html><head><title>502A gateway or load balancer pagenginx, Cloudflare, an ALBThe upstream never answered; your API is not involved
<?xmlLegacy endpoint, or content negotiation you lostA SOAP or Atom handlerAccept header, or the wrong path version
Binary block, then readable textA container: gzip, ZIP, a PDFA file endpointThe content coding step has not been undone

One of these is a real API bug. The others are correct behaviour that a JSON-first client mishandles.

If the response alternates between media types with no code change, look at the cache and the Vary header, not the parser. A cache keyed on Accept can hand your JSON request a cached HTML variant, which reproduces only for some clients and never in your integration test.

Errors

Read the error body before you invent one

RFC 9457 standardised what an API error body should say, and it is the only part of this page that is about reading rather than decoding. A problem document has five defined members, and each answers a different question than the one most teams put in their error payload.

The five defined members and what to do with each
MemberQuestion it answersWhat is legalDebugging use
typeWhich error class is thisA URI reference; defaults to about:blankA stable string to group on, and often a documentation URL
titleWhat is this class calledShort, human-readable, fixed per typeDo not parse it; it is allowed to change wording
statusWhich HTTP status carried itA number, consistent with the response statusSeparates 400 from 422 from 403 without reading prose
detailWhat happened this timeHuman-readable, occurrence-specificThe one field worth logging verbatim
instanceWhere to find out more about this occurrenceA URI referring to this occurrenceA correlation id to take to the log

Extension members are explicitly permitted, so a valid problem document can also carry your errors array, retry hints or field lists.

Three misreadings cost time. First, treating type as a link: it is a URI reference used as a global identifier, and about:blank is the default for a problem with no registered type, not a broken field. Second, reading title as a machine value: it belongs to the type, not the occurrence, and a server is free to re-word it, so group by type, never by title. Third, ignoring status inside the body when it disagrees with the status line: that disagreement is a server bug where someone built the error from an internal exception type and let the transport pick the code. Capture both numbers in your logs; the pair identifies the bug even when neither alone does.

a problem document worth reading8 lines
{
  "type": "https://api.example.com/errors/validation",
  "title": "Request failed field validation",
  "status": 422,
  "detail": "The \"since\" parameter must be an ISO 8601 date.",
  "instance": "/requests/01J9XK2M4Q",
  "errors": [{ "path": "/since", "expected": "date" }]
}

The last two members are extensions. The detail here tells you the parameter and the format; that sentence is why you read the body.

The meta-lesson for every section that follows: an error response is the only payload in your system that is supposed to explain itself. When a 400 arrives, its body is the diagnosis. Parsing it as an instance of your success schema and reporting a mismatch is the most reliable way to turn a five-second answer into a half-day of guessing.

Tokens

JWT: decodable is not verified

A JSON Web Token in its compact form is three base64url-encoded segments separated by full stops: a header, a payload and a signature. Anyone can read the first two. That is not a bug and not a secret: RFC 7519 describes the token as a structure whose segments are encoded, not encrypted, and base64url is an encoding. The honest statement of what a decoder gives you is that the payload is readable and that the signature is unverifiable without the key, and a tool that shows you a decoded payload without saying so is teaching the wrong lesson.

what the header is really telling you7 lines
{
  "alg": "HS256",
  "typ": "JWT",
  "kid": "us-east-1-2026-11"
}
--- decoded, not verified ---
the header is attacker-supplied text: never route on it

A kid that names a key, an alg that names an algorithm, and no proof that either came from the party that issued the token.

Two header fields deserve immediate suspicion. An empty third segment means nothing proves where the token came from. A header asking for alg: none or omitting alg entirely is the original JWT bypass class: a verifier willing to accept it treats any signature as valid. And a MAC algorithm paired with a kid is the shape that invites key confusion when a server resolves the key from a value the client controls.

The failure mode that sends most people to a decoder is a token that will not decode, and almost all of those are transport damage rather than auth damage. A signature segment that travelled through a query string unescaped can have had its + read as a space by form decoding, which surfaces in the base64 layer as an invalid-character error naming the offending symbol. Strip that space and the length becomes one more than a multiple of four, which the decoder reports as an impossible length. And a padded segment whose padding appears before other characters is reported as padding in the middle — the signature of two values concatenated or a value truncated, not of a bad token.

exp, nbf and iat: seconds, milliseconds and clock skew

The three time claims are defined as a NumericDate: a JSON number holding the count of seconds from the UTC epoch, ignoring leap seconds. Not milliseconds. Not local time. A huge fraction of expired-token reports are somebody writing milliseconds into a seconds field, and the second-largest group is a generator whose clock is not the verifier's clock.

Unit and zone mistakes, and the number you would actually see
What the generator didThe value in the payloadHow it readsSymmetric symptom
Wrote milliseconds1762000000000Year 57,000 if read as secondsDetected by a divide-by-1000 heuristic
Set exp as iat plus 3600, with iat in millisecondsA one-hour tokenValid for 3.6 secondsIntermittent auth failures under load
Formatted local wall-clock time as a numberOff by the zone offsetHours early or lateWorks in dev, fails in prod
Wrote exp as a JSON string"1762000000"No row at all: only numbers are renderedThe claim silently disappears from the report
Verifier clock is unsynchronisedCorrect valueExpired seconds agoOnly some nodes reject the token

The string case is the sneaky one: the claim renderer looks for a JSON number, so a quoted timestamp produces no expiry row and no complaint.

Read the raw number before the friendly date, then check three things in order: whether the unit is seconds, whether the generator and the verifier agree on which instant is now, and whether the algorithm in the header is the one your code expects. A token that fails all three and still works on a colleague machine is a clock problem, and no amount of decoding will tell you more.

Navigation

Finding the array: paths and pagination

Most payloads that resist reading are not big; they are deep. You need one value out of a document whose interesting collection lives at response._embedded.items[37].links.next.href, and guessing the path is how people end up formatting 2 MB again. Two notations exist for naming a location, and they solve different problems.

The two path notations, and when each one is the right thing to type
NotationRootExamplesUse it when
JSON PointerThe empty string, which means the whole document/data/items, /data/items/0/id, /a~1b/c~0dYou need exactly one value, addressed deterministically
JSONPathThe dollar sign$.data.items[*].id, $..id, $.items[0:10]You need a set of values, or a filter over a collection

Pointer escapes: a key containing a solidus is written ~1 and a key containing a tilde is written ~0.

The validator gives you the shape that tells you which expression to write. Root says whether the document is an object or an array, Records is the length of the top-level array, Largest array is the longest array at any depth, so when Records is one and Largest array is five hundred the collection is wrapped. The structure outline walks the first object and the first array element, printing each key with its value kind, which is where you read "items": [500 items] and write the pointer yourself.

Six pagination failures, in the order they are usually discovered

the shapes that break4 lines
{"data":[…],"meta":{"page":1,"limit":1000,"returned":100,"total":4982}}
{"data":[…],"meta":{"next_cursor":"eyJvIjoiMjAyNi0xMS0xMiJ9","has_more":true}}
{"data":[…],"meta":{"next_cursor":"eyJvIjoiMjAyNi0xMS0xMiJ9","has_more":true}}   <- identical cursor: you are looping
{"data":[…50 records…],"meta":{"next_cursor":null,"has_more":false}}                <- limit silently capped at 50

Returned against limit is the first pair to read. A next_cursor identical to the one you sent is a loop, not a last page.

The cursor in that second line decodes to a date, and that is the point: opaque cursors are usually base64, and the decoder will tell you whether it is text, JSON, or binary, which is how you learn that paging is driven by a timestamp and that records inserted with the same timestamp are the reason page three repeats rows from page two. Repeats across pages are almost always an ordering problem: a sort on a non-unique column gives the server no stable tie-break, so the fix is an order on (timestamp, id), and the diagnosis is a duplicate count over the exported id column.

Comparison

Duplicate keys and diffing without noise

The word duplicate covers two distinct problems in an API response, and conflating them wastes afternoons. One is a repeated name inside a single JSON object, which is a document defect. The other is a repeated record across an array, which is a data defect and usually a pagination artefact of the kind the previous section describes.

Duplicate names inside one object

RFC 8259 §4 says names within an object SHOULD be unique. SHOULD is not MUST, so a document with the same key twice is legal JSON, and the meaning is delegated to whoever reads it. The consequence is data loss by default: parsers that build a map keep one value per name, and the overwhelmingly common behaviour is last-value-wins.

a real duplicate, formatted8 lines
{
  "id": "ord_8812",
  "status": "pending",
  "amount": 4200,
  "status": "cancelled"
}
warning: Duplicate key "status" in the same object (first occurrence: line 2)
JSON.parse value: "cancelled"     this tool keeps both lines when printing

Same key, two values, one document. Whatever your parser does, one of these two is gone before your code sees it.

Duplicates come from one of four places: a body assembled by concatenating strings, an envelope that merges an upstream payload into its own object, a template that emits an optional field and then a default one, or two serialisers in the same pipeline writing the same field with different casing rules. The first is fixable in five minutes; the other three explain why it reproduces only for some records. Treat any duplicate in an API response as a producer bug and find the serializer that emitted it.

Diffing two responses without diffing the noise

You have two responses and a text diff shows four hundred changed lines, of which six are interesting. The ratio is not bad luck. JSON has four properties that make naive text diffing systematically misleading:

Four reasons two identical payloads do not match as text
PropertySpec basisWhat the diff showsWho can rewrite it
Object member order is not significantAn object is an unordered collection of name and value pairsEvery line moved, nothing changedAny serialiser, and your own language at the next round trip
Number literals keep whatever spelling was writtenRFC 8259 §6 grammar, with range and precision left to implementations1e3 against 1000 against 1000.0JSON.parse rewrites all three; this formatter rewrites none
Insignificant whitespace is allowed anywhere outside stringsRFC 8259 §2 is whitespace, one value, whitespaceThe entire file, if one side was pretty-printedFormatters, minifiers and template engines
Escaping has many valid formsRFC 8259 §7 defines the escapes; nothing forbids \u00e9 over éA quoted name looks changedUnicode-escaping writers, and non-JSON-aware encoders

The fourth one is the least obvious and the most common in cross-language diffs: two encoders, one string, two byte sequences.

The normalisation ladder, in the order that costs least. Step one: collapse whitespace on both sides with the minifier, which prints the parsed tree without insignificant space and emits number literals exactly as they were written, so it removes formatting differences without creating numeric ones. If the two compact forms are byte-identical, you are done. Step two: normalise key order on both sides with the formatter. Sorting both sides identically turns a reordered payload into an empty diff; sorting one side only makes your diff a lie.

Step three, and this is where people get hurt: do not use a language round trip as your normaliser. Passing both files through a JSON parser and back out looks principled and is destructive in two specific ways. Numbers are re-emitted in the shortest form that parser prefers, so 12.50 becomes 12.5, and any integer above 2^53 minus one comes back as a different number entirely. And member order is rewritten by the language: JavaScript puts integer-like keys first in ascending order regardless of how they were written, so a round trip through JSON.parse reorders part of your document on its own.

Streaming

Streaming bodies: NDJSON and SSE

A bulk import body, a log download and a machine-learning response stream are not one JSON document. They are many documents separated by something, and the strict parser is right to reject them: RFC 8259 §2 defines JSON text as whitespace, exactly one value, whitespace. The interesting question is what separates the records, because that is where the conventions differ and where the truncation bugs live.

Two ways to put many JSON values in one byte stream
ConventionSeparatorMedia typeWhere it bites
NDJSON, JSON LinesOne LF after each valueapplication/x-ndjsonA missing final newline, a pretty-printed record, an embedded raw newline
JSON text sequenceRS before each value, LF after itapplication/json-seqInterleaved writers, values that are not self-delimiting
One array of recordsCommas, no per-record newlineapplication/jsonNothing can be appended; you must rewrite the file

RFC 7464 uses RS to mark a record start and LF to mark a record end, so a reader can notice a value that never terminated itself.

The formatter recognises NDJSON: when the strict parse fails it splits the input on line breaks, tries every line on its own, and if all of them parse it reports a record count. That count is what you reconcile against the importer; if it does not match the rows the server says it sent, you have a truncated stream, not a formatting problem.

three lines, three different faults5 lines
{"ts":"2026-11-12T09:04:11Z","msg":"cache miss","trace":"a91f"}
{"ts":"2026-11-12T09:04:11Z","msg":"up {"ts":"2026-11-12T09:04:11Z","dur_ms":4}
{"ts":"2026-11-12T09:04:12Z","note":"line one
line two","trace":"b3c0"}
{"ts":"2026-11-12T09:04:13Z","msg":"flushed

Line two is two writers on one descriptor. Line three is a raw newline inside a string. Line four is the truncated tail.

Each fault has a distinct signature. The interleaved line errors near the end of the row, because the object never closes before another object starts. The embedded newline produces the diagnostic that raw newlines are not allowed inside JSON strings, naming the line — the fastest way to find the writer that pasted a stack trace into a field without escaping it. The truncated final record produces an unexpected-end error and is the only one of the three the server caused. Several bulk endpoints split on the separator and treat the remainder as a record, so a writer that omits the last LF gives an error naming the final line and nothing else.

Server-sent events: JSON inside a text protocol

An event stream is the least JSON-like thing on this page, and the most commonly mis-debugged. The response is served as text/event-stream with UTF-8 text. Each message is a block of field: value lines terminated by a blank line, which is what dispatches the event. The fields are data for the payload, event for a named type, id for the last event id, and retry for the reconnection delay. When consecutive lines begin with data:, the client concatenates them with a newline between each.

a stream and what you must extract11 lines
: keepalive
id: 41
event: delta
data: {"choices":[{"index":0,"finish_reason":null}]}
data: [DONE]

id: 42
data: partial
data: payload

retry: 3000

Two blank-line-terminated messages plus a retry hint. The payload of the second message is the two data lines joined by a newline character.

Four stream-specific failures, each with a distinct name. The sentinel: [DONE] parsed as JSON reports that a value was expected, and a client that swallows that error has turned a protocol terminator into an exception — filter the sentinel before the parser, not after it. The keepalive: a comment line fed to a JSON parser produces an error at the colon, which means the frame was never unwrapped, which is your job, not the server's. The multi-line payload: if the writer split a string value across data lines you get the raw-newline-in-a-string error, which is a server-side framing bug worth reporting. Reconnection: the last event id is what the client sends back, so an id that is not monotonic, or absent, produces duplicated events or a silent gap. Buffering: a proxy that buffers the response turns a live stream into a burst at the end, and the mitigation is an explicit no-buffering response header at the proxy plus a flush at the application.

Request side

Query-string bugs

Half of the responses you cannot read were caused by a request you did not send, and the query string is where that happens. A URI carries two meanings at once: the characters, and the delimiters that say where components and parameters start. RFC 3986 defines the syntax but not your parameter format, and every bug in this section comes from that gap.

Four rules, four bugs. Rule one: separate the components before you decode anything. RFC 3986 §2.4 says components must be parsed and separated before the percent-encoded octets inside them can be safely decoded. Do it in the other order and a value containing &admin=1 becomes a parameter, which is the whole injection class in one sentence. Rule two: a plus is not a space, except when it is. RFC 3986 §7.3 states that treating a plus as a space is not part of URI syntax and should not be relied on without an explicit agreement between sender and receiver. That agreement is what your framework either has or does not have, with C++ arriving as C as the reported case. Rule three: never encode twice. Percent-encoding is idempotent only in one direction, and encoding an already-encoded string turns %20 into %2520. This is the bug behind a great many OAuth failures: a redirect URI encoded by the client and encoded again by the library changes the string that gets signed, so the signature check fails on a value that looks correct in the log. Rule four: normalise before you compare. %41 and A denote the same URI but are not the same string, so two URLs that differ only in escaping will not match a cache key, a signature base string or a permission rule.

What the URL inspector reports, and the bug each finding points at
FindingSeverityThe underlying bugFix on which side
repeated-keywarningNothing defines a repeated key: one framework keeps the last, one builds an array, one binds the firstSender: emit one key, or the array convention your server expects
ambiguous-pluswarningA literal plus in a query value, which form decoding turns into a spaceSender: encode the plus; receiver: agree on the convention
multi-layerwarningNested percent-encoding that validators inspect only one layer ofSender: encode exactly once
raw-spacewarningA space in a URI, silently turned into %20 by the address bar but rejected from codeSender: encode it
path beginning with //infoA path that parses as an authority, the classic open-redirect and SSRF mechanismServer: validate the target, do not concatenate
dangerous-schemeerrorA scripting scheme in a URL that will be assigned to a link or a redirectServer: allow-list http and https

Decode keys and values with the plus-as-space rule in the inspector, but check the toggle in the decoder against the context: it is right for a form body, wrong for a path.

Checklist

Symptom to first finding

The order below is the order that resolves most reports. Read the row that matches what you can see, do the step, and only move to the next row when the current one has given you a number or a finding rather than a suspicion.

Symptom to page to first finding, in runbook order
#If you see thisOpenRead this first
1A status code you did not expectYour client, with headersContent-Type, Content-Encoding, Transfer-Encoding against Content-Length
2A body that will not parseJSON ValidatorThe error line and column, and whether the byte count matches
3A body that parses but is unreadableJSON ValidatorThe structure outline, Records, Largest array, Depth
4Text with wrong accents or a stray markJSON FormatterThe utf8-bom and invalid-whitespace diagnostics
5Bytes that look like a containerBase64 DecodeThe magic-bytes match, and whether it is UTF-8 at all
6A token you need to understandBase64 DecodeHeader alg, kid, then exp and iat as raw numbers
7A record that seems to be missingJSON ValidatorThe duplicate-key warning with its first-occurrence position
8A body that is many documentsJSON FormatterThe NDJSON record count, then repair it into an array
9A query that returned the wrong thingURL EncoderThe inspector parameters, plus repeated-key and multi-layer
10Two payloads you must compareJSON MinifierBoth compact forms, then both with keys sorted

Steps 1, 5 and 6 are the three that most often end the investigation without touching a formatter at all.

content coding
A transformation of the representation data named in Content-Encoding, undone left to right: RFC 9110 §8.4.
transfer coding
A transformation of the message content for safe transport, chiefly chunked framing: RFC 9112 §7. Never part of your data.
NumericDate
A JSON number of seconds from the UTC epoch, ignoring leap seconds, used for exp, nbf and iat. Not milliseconds.
unverified token
A JWT whose segments you have decoded. Readable claims are evidence about intent, not evidence about origin.
canonical percent-encoding
Uppercase hex digits with unreserved characters written literally: RFC 3986 §6.2.2, the only version safe to compare or sign.
insignificant whitespace
Space, tab, LF and CR between tokens, permitted by RFC 8259 §2 and the only thing minification removes.

Answers

Questions about debugging HTTP APIs

Can I check whether a JWT is valid by decoding it?

No. Decoding reads the header and payload; it does not verify the signature. A decoded token tells you what the token claims (alg, kid, exp, issuer), which is useful when debugging clock skew or unit mismatches. It tells you nothing about who issued it. Authenticity requires checking the signature over the exact header and payload bytes with the algorithm pinned by your code, never read from the header.

Why does my JWT fail after it passes through a URL?

A base64url signature containing "+" survives a query string badly: form decoding turns "+" into a space, so the base64 decoder reports an invalid character or a length that is one mod four. Percent-encode the token once, do not encode it twice, and check the URL Encoder inspector for the ambiguous-plus and multi-layer warnings before blaming the auth server.

Should I minify a JSON fixture before committing it?

No. A one-line fixture makes every future change a whole-file diff with no context, so review becomes impossible and blame stops being useful. Commit the pretty form; if size matters for a payload-budget test, generate the compact form at build time from the pretty source and keep the generator. Run the validator first, because duplicate names and unsafe integers pass a round trip silently.

My bulk-import endpoint says the body is invalid on the last line only. What is wrong?

A missing trailing newline, not a bad record. Newline-delimited JSON ends each record with LF, and several bulk APIs require the final LF because they split on it and treat the remainder as an incomplete record. Confirm your writer flushes a newline after the last object, then check with the formatter that every line parses on its own.

Related

Next up

Sources and further reading

  1. [1]RFC 9110: HTTP Semantics — Section 8.4 defines content codings and Content-Encoding; section 8.3 makes Content-Type the media type of the representation; section 12.5.1 covers content type negotiation with Accept. (accessed November 12, 2026)
  2. [2]RFC 9112: HTTP/1.1 Messages — Section 7 defines transfer codings and the chunked transfer coding; section 6.3 excludes 1xx, 204 and 304 from carrying any body. (accessed November 12, 2026)
  3. [3]RFC 8259: The JavaScript Object Notation (JSON) Data Interchange Format — Section 2 fixes JSON text as whitespace around exactly one value; section 4 says names within an object SHOULD be unique; section 6 gives the number grammar; section 8.1 requires UTF-8 for text exchanged between systems. (accessed November 12, 2026)
  4. [4]RFC 7519: JSON Web Token (JWT) — Three base64url-encoded segments separated by dots; NumericDate as a JSON number of seconds from the UTC epoch; the exp, nbf and iat claims. (accessed November 12, 2026)
  5. [5]RFC 3986: Uniform Resource Identifier (URI): Generic Syntax — Section 2.1 defines pct-encoded; section 2.4 requires components to be separated before encoded octets are decoded; section 7.3 states that treating a plus as a space is not part of URI syntax. (accessed November 12, 2026)
  6. [6]RFC 7464: JSON Text Sequences — The application/json-seq media type and the ABNF 1*( RS JSON-text LF ), where the trailing LF lets a receiver detect a truncated value. (accessed November 12, 2026)
  7. [7]RFC 9457: Problem Details for HTTP APIs — The application/problem+json media type and its type, title, status, detail and instance members, with extension members permitted. (accessed November 12, 2026)
  8. [8]MDN: Using server-sent events — text/event-stream as the required response type; the data, event, id and retry fields; consecutive data lines concatenated with a newline; proxy buffering as the reason streams stall. (accessed November 12, 2026)