GraphQL responses and errors

Connection responses

search, childrenOf and descendantsOf return GraphQL connections:

json

{
  "data": {
    "descendantsOf": {
      "edges": [
        {
          "cursor": "opaque-cursor-from-server",
          "node": {"id": "3127593", "title": "Museo Nacional del Prado"}
        }
      ],
      "pageInfo": {"hasNextPage": true, "endCursor": "opaque-end-cursor"}
    }
  }
}

This is an illustrative shape, not a captured GraphQL response. Do not reuse placeholder cursors.

Single-node operations return an object under data.node or data.bySlugId, or null when not found. Global counts return an integer under data.nodeCount. There is no totalCount field on connections in the documented API.

Error envelope

GraphQL errors use the conventional top-level errors array, for example:

json

{ "errors": [{ "message": "GraphQL validation failed" }] }

This is a shape illustration; actual server messages, extra keys and partial-data responses vary. Check both HTTP status and any GraphQL errors array.

HTTP status codes on the public reference

Code	Meaning stated on the current public page
`200`	Execution completed; inspect `errors` for partial failure
`444`	Syntax, unsupported-field or schema-validation failure
`429`	Request rate limited; wait and retry

The GraphQL endpoint is limited to 200 requests per minute. If you receive a rate-limit error, wait and retry with an increasing delay.

Error-handling checklist

Check the HTTP status and parse JSON if available.
Examine errors even when the status is 200.
On 429, use backoff; respect Retry-After if the server supplies it.
Avoid retrying invalid GraphQL documents unchanged.
Log IDs and diagnostics without exposing sensitive user information.