How the API Responds
Every GraphQL request goes to the same endpoint and gets one HTTP response. How that response is written depends on
the query: small answers are sent in one piece, large lists are written as they are read, and a query that uses
@defer or @stream is answered in parts. You never choose a mode with a header or a parameter. The API picks it
and tells you which one it used.
Response Modes
| Mode | When | Body | What your client needs |
|---|---|---|---|
buffered | Most requests. | One JSON document, Content-Type: application/json. | Nothing special. |
streamed | A query whose top-level list is long. See Streamed Responses. | The same JSON document, sent with Transfer-Encoding: chunked while the data is still being read. | Nothing special if it reads the whole body. Read it as a stream to keep memory flat. |
incremental | A query that uses @defer or @stream. | multipart/mixed: an initial JSON document, then more parts. | A client that reads multipart responses. |
A buffered and a streamed response to the same query carry the same JSON. Any HTTP client that waits for the
end of the body and then parses it reads both the same way.
Response Headers
| Header | Sent with | Meaning |
|---|---|---|
x-mapped-response-mode | Every GraphQL response that was executed. | buffered, streamed or incremental. A request refused before it is executed (a missing token, a malformed body) does not carry it. |
x-mapped-billable-bytes | buffered responses to authenticated requests. | The size of the response data that the request is billed for, in bytes. |
x-mapped-billable-rus | buffered responses to authenticated requests. | The request units the request is billed for. |
Content-Type | Every response. | application/json, or multipart/mixed; boundary="-"; deferSpec=20220824 for an incremental response. |
A streamed or incremental response sends its headers before its size is known, so it does not carry
x-mapped-billable-bytes or x-mapped-billable-rus. The request is billed the same way; only the headers are
missing. If your integration reads those headers, check x-mapped-response-mode first.
Billing counts the data of a response.
Errors
A field that fails is null in data and has an entry in errors, in every mode. What differs is where the errors
are:
- In a
bufferedresponseerrorsis part of the one document, as usual. - In a
streamedresponseerrorscomes afterdatain the document, because the data has already been sent when a later row fails. GraphQL allows either order; a JSON parser does not care. - In an
incrementalresponse an error belongs to the part it happened in.
Size Limit
A response has a maximum size. When a buffered response would pass it, the request fails with an error and no data.
A streamed or incremental response that passes it part-way is cut off: the connection is closed before the
body is complete, so your HTTP client reports a failed request instead of handing you a response that only looks
complete. Ask for less in one request: filter the list, select fewer fields, or use the paginated fields.
A Response That Is Cut Off
A streamed or incremental response can end early: the size limit, a failure on our side after the first bytes
have gone, or a network problem. It is never ended in a way that parses as a complete answer.
- A
streamedresponse that is cut off is not valid JSON, and the connection ends with an error. - An
incrementalresponse that is cut off ends without its closing boundary and without a part that says"hasNext": false.
Treat either as a failed request and retry it.