Errors and limits
Two kinds of failureโ
A GraphQL request can fail in two places, and they look nothing alike:
| Transport failure | Query failure | |
|---|---|---|
| When | Before the GraphQL engine runs | While parsing, validating or executing the document |
| Status | HTTP 4xx / 5xx | HTTP 200 |
| Body | RFC 9457 problem document | GraphQL envelope with an errors array |
| Examples | Missing or expired token, insufficient grant, malformed JSON, query over 10,000 characters | Unknown field, wrong argument type, a rejected filter, a limit exceeded |
Never infer success from the status code. A query failure is a 200. Always check whether errors is
present.
Response envelopeโ
{
"data": null,
"errors": [
{
"message": "Human-readable explanation.",
"locations": [{ "line": 1, "column": 3 }],
"path": ["equipment"],
"extensions": {
"code": "https://problems.tourfold.com/graphql/invalid-pagination",
"title": "Invalid pagination arguments",
"data": { "first": 5, "last": 5 },
"classification": "DataFetchingException"
}
}
],
"extensions": {
"cost": { "estimated_rows": 23, "limit": 100000 }
}
}
Later examples on this page omit classification for brevity; it is present on every error.
| Field | |
|---|---|
message | Human-readable text. Written for a developer, not a contract โ do not match on it. |
locations | Where in the query document the problem is. |
path | The response path of the field that failed. |
extensions.code | The stable identifier. Branch on this. |
extensions.title | Short label for the problem type. |
extensions.data | Per-occurrence detail โ the measured value, the rejected input. |
extensions.errors | Sub-errors, when one failure has several parts. |
extensions.classification | The GraphQL engine's own coarse category (ValidationError, DataFetchingException). Informational, not part of this API's contract โ it belongs to the library and may change with an upgrade. Branch on code. |
extensions.code is a Type URI, and it is the same string a REST error carries in type. One
identifier covers both surfaces, so a client that already handles Tourfold's REST errors does not need a
second vocabulary. There is deliberately no wrapping problem object; title and data sit flat beside
code.
There is no status field. The response is always HTTP 200, so there is no status to report.
How far a failure propagatesโ
GraphQL replaces a failed field with null and reports the reason in errors. How much else survives
depends on whether that null is allowed where it lands, and on this API the answer is usually "not much":
A failed root connection nulls the whole data. Root fields are non-null (equipmentConnection!), so a
null there is not permitted and the failure propagates to the enclosing object โ which is data itself.
Every example on this page therefore shows "data": null, not "data": { "equipment": null }.
A failed nested relation nulls only that field. To-many and to-one relation fields are nullable, so a
failure inside one stops there and its siblings keep their data. That is where you will genuinely see a
response carrying both data and errors.
An invalid document executes nothing. An unknown field or a wrongly typed argument is caught before
execution, and then the data key is absent altogether โ not null. Nothing ran, and "no data" is a
different claim from "the data is null". Every problem in the document is reported at once.
So do not write a client that assumes partial data is always available. Check errors first, and treat
data as possibly null and possibly missing.
Engine errors use one stable codeโ
Errors raised by the GraphQL engine before execution โ syntax errors, unknown fields, and type
mismatches โ use graphql/invalid-query. The engine's original message, locations, and informational
classification are preserved, but clients can branch on the stable Tourfold code instead of matching
English text.
{
"errors": [
{
"message": "Validation error (FieldUndefined@[equipment/cpu_processor]) : Field 'cpu_processor' in type 'equipment' is undefined",
"locations": [{ "line": 4, "column": 5 }],
"extensions": {
"code": "https://problems.tourfold.com/graphql/invalid-query",
"title": "Invalid GraphQL query",
"classification": "ValidationError"
}
}
]
}
Note that the data key is absent because validation prevented execution. classification remains the
engine's own category and is not the stable contract; extensions.code is.
Check the schema endpoint for the fields your workspace actually has โ and note that a missing field may be a name collision rather than a typo.
Error catalogโ
Failures specific to GraphQL take the graphql/ namespace:
extensions.code | Raised when | data carries |
|---|---|---|
graphql/invalid-query | The document cannot be parsed or validated against the tenant schema | โ |
graphql/query-too-deep | The document nests more Relay levels than allowed | depth, limit |
graphql/query-too-complex | The query's estimated row count exceeds the budget | cost, limit |
graphql/query-timeout | Execution exceeds the wall-clock deadline | timeout_ms |
graphql/filter-too-deep | A where argument nests too many levels | depth, limit |
graphql/invalid-cursor | A cursor was not produced by this API | cursor |
graphql/invalid-pagination | Pagination arguments conflict, are negative, or exceed the maximum page size | the offending arguments and, for an oversized page, maximum |
Everything else reuses a type from the general catalog:
extensions.code | Raised when |
|---|---|
access-denied | A per-type ACL denies a root or relationship field. extensions.data carries reason: not_member and type: object:<slug>. |
validation-failed | A filter operand is rejected โ for example, an invalid UUID or an empty _in / _contains list. The offending field is named under extensions.errors. |
unknown-error | An unexpected server-side failure. The message is deliberately generic; the detail is logged server-side. |
Sub-errorsโ
When one failure has several parts, they appear under extensions.errors. A sub-error carries only what
varies per occurrence โ code, message, path, data โ and does not nest further. path is a field
path, the way GraphQL addresses everything else, so a response never mixes field paths with JSON Pointers.
Converting to a REST problem document renders it as an RFC 6901 pointer.
Limitsโ
| Limit | Value | Enforced |
|---|---|---|
| Query document length | 10,000 characters | HTTP 422 with a problem document |
| Query depth | 12 Relay levels | graphql/query-too-deep |
| Query cost | 100,000 estimated rows | graphql/query-too-complex |
| Execution time | 10 seconds wall-clock | graphql/query-timeout |
| Page size | 100 max; default 20 root, 10 nested | graphql/invalid-pagination when exceeded |
Filter (where) nesting | 4 levels | graphql/filter-too-deep |
Relationship order_by nesting | 1 to-one hop | A deeper path or to-many hop is not expressible in the schema |
Query depth and filter nesting are independent controls with different values: one bounds relation
traversal, the other bounds a where tree. Raising one does not affect the other.
The execution deadline starts when GraphQL begins running the operation. At ten seconds the API returns a
normal GraphQL envelope with data: null, graphql/query-timeout, and the configured deadline in
extensions.data.timeout_ms. It also interrupts the operation's worker virtual thread so cooperative
database and application work can stop. Clients should treat the response as failed and may retry only
when the operation and their usage pattern make a retry safe.
Counting query depthโ
Depth is counted in selection levels, not relation hops โ which is why 12 is smaller than it sounds:
- A bare connection already costs 4: root field โ
edgesโnodeโ leaf. - Each further to-many hop costs 3: relation field โ
edgesโnode. - Each to-one hop costs 1.
So a one-hop query is depth 7 and a three-hop query is depth 13 โ over the limit. Split a deep traversal into separate queries, or start from the other end of the relation.
{
"data": null,
"errors": [
{
"message": "Query depth 15 exceeds the maximum of 12. Each to-many hop costs three levels (field, edges, node); select fewer levels or split the traversal into separate queries.",
"extensions": {
"code": "https://problems.tourfold.com/graphql/query-too-deep",
"title": "Query too deep",
"data": { "depth": 15, "limit": 12 }
}
}
]
}
Query costโ
A response reports what the query cost whenever the request got far enough to be analysed:
"extensions": { "cost": { "estimated_rows": 23, "limit": 100000 } }
When it is present: on a successful execution, and on a query-too-complex refusal โ which is the
point, since it lets you see how far over budget you were.
When it is absent: when the request never reached cost analysis. A syntax error or a validation error is
caught earlier, and there is no executable operation to price. A query-too-deep refusal is also earlier,
because the depth guard runs first. Treat extensions.cost as optional and never assume it is there.
estimated_rows measures how far the response can expand โ how many nodes the query can be asked to
produce. It is not an upper bound on database rows read, statements issued, or time spent: some internal
work (resolving a relation filter, or a nested relation once per parent row) is not proportional to the
response and is not charged here. Use it to keep response sizes sane, not as a performance guarantee.
The score is a row count, not a field count:
- A plain field costs
1 + (its children). - A connection costs
1 + pageSize ร (its children), wherepageSizeis your validfirst/last, or the applicable default when you gave neither. Cost estimation bounds an oversized value at 100 before execution; the connection then rejects that value as invalid pagination.
The multiplication is the part to internalise: a connection pays for its whole subtree once per row. So this query โ
{
equipment(first: 2, order_by: [{ name: asc }]) {
totalCount
pageInfo { hasNextPage endCursor }
edges { cursor node { id name asset_tag operational } }
}
}
โ scores 23:
| Selection | Cost |
|---|---|
totalCount | 1 |
pageInfo { hasNextPage endCursor } | 1 + 2 = 3 |
node { id name asset_tag operational } | 1 + 4 = 5 |
edges { cursor node } | 1 + 1 + 5 = 7 |
equipment connection | 1 + 2 ร (1 + 3 + 7) = 23 |
Two consequences follow, and they are the opposite of what a field-count budget would suggest:
- A wide page is cheap. Selecting 20 columns of a 25-row page is a few hundred rows.
- A narrow deep traversal is expensive. One column, paginated 100 ร 100 ร 100, is a million rows and is refused โ even though the document mentions barely a handful of fields.
If a query is refused, the cheapest fix is almost always a smaller first on the innermost
connection, because that is the factor multiplied most times.
{
"data": null,
"errors": [
{
"message": "Query is estimated to materialise 3003001 rows, above the budget of 100000. A connection multiplies its subtree by its page size โ request smaller pages or select fewer nested fields.",
"extensions": {
"code": "https://problems.tourfold.com/graphql/query-too-complex",
"title": "Query too complex",
"data": { "cost": 3003001, "limit": 100000 }
}
}
]
}
The cost limit applies per query. It is not a budget over time, so staying under it on each individual request is not on its own a reason to issue them as fast as possible โ keep request rates proportionate to what your integration needs, and expect rate limiting on sustained heavy use.