A nightly sync from a partner’s GraphQL API had run for weeks without a single failed execution. Green across the board in the console. Then someone asked why one column had been empty since the previous Tuesday. Not sparse. Empty. Every row, every night, for six nights.

The API had started returning a field-level error on that one field. Status code 200. A populated data block. An errors array sitting right next to it. The fetcher parsed data, wrote the records to S3, exited zero, and the orchestrator logged a success. Nothing in the stack was wrong, exactly. Everything in the stack was checking the wrong thing.

This post covers how to build a GraphQL data ingestion pipeline on AWS that fails honestly. It is organised by failure family rather than by service, because the AWS wiring is the easy part. The hard part is that GraphQL breaks four assumptions that REST ingestion quietly relies on, and every one of them fails silently by default.

Why GraphQL ingestion breaks the habits REST taught you

Most ETL code carries three inherited reflexes from years of REST work: the status code tells you whether it worked, the response shape is the server’s business, and rate limits are counted in requests. GraphQL invalidates all three.

• The status code is not the contract. The GraphQL over HTTP specification says a server should return 200 even when field errors are raised during execution, because a partial response is still a successful execution.
• You own the response shape. The selection set is written by you, which means schema drift shows up as a query that stops being valid, not as a payload that changes underneath you.
• Cost is query-shaped, not endpoint-shaped. One endpoint can cost almost nothing or blow your entire budget depending on how deeply you nested it.

Each of those becomes a distinct failure family. Let’s take them in the order they bite.

Failure one: the 200 OK that quietly ate a column

This is the one that costs the most and shows up the latest. GraphQL splits errors into two categories, and they behave completely differently on the wire.

• Request errors happen before execution starts: syntax errors, validation failures, bad variable coercion. No data key is returned at all. Nothing executed.
• Field errors happen during execution: a resolver threw, a downstream service timed out, a permission check failed. Execution continues, the failed field goes null, and you get data and errors together.

Field errors are the dangerous ones for ingestion, because they look exactly like success to anything that only inspects the transport layer. Worse, GraphQL’s null propagation rules mean a single failing non-null field bubbles up to the nearest nullable ancestor, so one broken resolver can hollow out an entire nested object while the surrounding rows land normally.

The fix is to make the response body the contract. Classify before you commit anything:

import json, urllib.request

class RequestError(Exception): pass
class FieldError(Exception): pass

def graphql(endpoint, token, query, variables):
    body = json.dumps({"query": query, "variables": variables}).encode()
    req = urllib.request.Request(
        endpoint,
        data=body,
        headers={
            "Content-Type": "application/json",
            "Accept": "application/graphql-response+json, application/json",
            "Authorization": f"Bearer {token}",
        },
    )
    with urllib.request.urlopen(req, timeout=30) as resp:
        payload = json.loads(resp.read())

    # The status code told us nothing. The body is the contract.
    if "data" not in payload:
        # Nothing executed. Query or auth problem. Do not retry blindly.
        raise RequestError(payload.get("errors"))

    if payload.get("errors"):
        # Partial response. data is populated but incomplete.
        raise FieldError(payload["errors"])

    return payload["data"]

Two things worth explaining. The Accept header asks for application/graphql-response+json, the media type the GraphQL over HTTP spec recommends, which lets a compliant server return a real 4xx for pre-execution failures instead of burying them in a 200. Servers that don’t support it fall back to application/json, so including both is free.

The second is the split between the two exception types. They need different handling. A request error is a bug in your query or a credential problem, and retrying it just burns budget on the same failure. A field error is transient often enough to be worth retrying, but never worth committing.

Deciding what “partial” means for your data

Failing the whole page on any error is the safe default and the one I reach for first. But it’s not always right. If you are pulling a hundred fields and one optional enrichment field is flaky, refusing every page forever is its own outage.

The workable middle ground is to classify by path. Every error object carries a path array pointing at the exact field that failed. Maintain a small allowlist of paths that are permitted to be null, fail the page on anything outside it, and emit the error count as a CloudWatch metric so a rising trend is visible before someone in finance notices.

Failure two: rate limits that never send a 429

Your retry logic almost certainly triggers on 429 and 5xx. Several major GraphQL APIs will throttle you without ever sending one.

GitHub’s GraphQL API is explicit about this: exceeding the primary rate limit returns a 200 response with an error message in the body and x-ratelimit-remaining set to zero. Your Step Functions retrier sees a success. Your Lambda sees no data. The run completes, having ingested nothing, and reports green.

The other half of the problem is that request counting is the wrong unit. Shopify’s GraphQL Admin API and several others price queries by calculated cost, using a leaky bucket. The server statically analyses your query before executing it, charges the bucket the worst-case requested cost, executes, then refunds the difference between requested and actual cost. That has a consequence people miss: a query asking for the maximum connection size gets charged as if every page were full, even when the last page returns three records.

The good news is that these APIs tell you the state of the bucket on every response, under the extensions key:

{
  "extensions": {
    "cost": {
      "requestedQueryCost": 72,
      "actualQueryCost": 38,
      "throttleStatus": {
        "maximumAvailable": 1000.0,
        "currentlyAvailable": 962.0,
        "restoreRate": 100.0
      }
    }
  }
}

Read those numbers, never hardcode them. Bucket size and restore rate vary by plan tier, and a query that works fine against a large merchant’s store will fail instantly against a small one. The pattern that holds up is a pre-flight check: before dispatching, compare your estimated cost against currentlyAvailable, and if you’re short, sleep for the shortfall divided by restoreRate.

On APIs that expose their own budget as a queryable field, ask for it in the same round trip rather than spending a second call to find out:

query BudgetCheck {
  rateLimit {
    limit
    cost
    remaining
    resetAt
  }
}

Two more things about concurrency. First, if you fan out across Lambda invocations, each worker’s local view of the bucket is wrong, because the bucket is shared. Multiple workers independently deciding they have headroom is the classic way to get throttled while every individual worker believes it’s behaving. Either centralise the token accounting or cap concurrency low enough that the arithmetic can’t go wrong.

Second, if the source offers a bulk or async export operation, use it for backfills. Paginating fifty thousand records through the interactive endpoint burns the same budget your incremental syncs need, and it competes with itself.

Failure three: cursors that don’t survive a restart

Most production GraphQL schemas follow the Relay cursor connections convention: first and after arguments, a pageInfo object with hasNextPage and endCursor, and edges carrying opaque per-item cursors.

query Orders($cursor: String) {
  orders(first: 100, after: $cursor) {
    pageInfo {
      hasNextPage
      endCursor
    }
    edges {
      cursor
      node {
        id
        updatedAt
      }
    }
  }
}

The filter argument for incremental sync is not standardised. Some schemas take a query-string filter, some take a typed timestamp argument, some expose nothing at all. Run introspection against the schema and find out rather than guessing, because a wrong argument name is a request error and your run will fail before it starts.

The failure here is subtle. Cursors are opaque and their validity is entirely up to the server. Some are stable positional pointers. Some encode a sort key and a snapshot identifier and expire. If a page-47 fetch fails and you retry an hour later with the stored cursor, you may get an error, or you may get results from a shifted window with a hole in the middle. The second outcome is worse, because it looks like it worked.

Three habits make restarts safe:

1. Checkpoint after the write, not after the fetch. A cursor recorded before the page lands in S3 is a promise you can’t keep.
2. Store a high watermark alongside the cursor. The cursor is your fast path. The watermark, taken from the newest record you actually committed, is your fallback when the cursor is rejected.
3. Overlap the watermark deliberately. Restart a few minutes before the last committed timestamp and deduplicate on the primary key downstream. Re-reading a handful of rows is cheap. Missing rows that arrived during a clock skew is not.

A DynamoDB item per source stream is enough state for all of this:

{
  "source": "orders",
  "run_id": "01hq7k...",
  "cursor": "eyJsYXN0X2lkIjoxMjM0fQ==",
  "high_watermark": "<updatedAt of newest committed record>",
  "pages_committed": 47,
  "status": "IN_PROGRESS"
}

Overlap only works if downstream deduplication is real. Write raw pages with an ingest-time partition and a run identifier in the object key, then let the curated layer resolve duplicates by primary key and latest updatedAt. If you write straight into a merged table with no dedupe step, overlapping restarts will double-count and you’ll have traded silent loss for silent inflation.

Failure four: the schema moved and nobody told you

GraphQL’s deprecation story is genuinely better than REST’s. Fields carry a @deprecated directive with a reason string, and introspection exposes it. The problem is that nothing forces you to look.

The failure mode is a field that gets deprecated, stops being populated, then eventually gets removed. Stage one is invisible: your query still validates, the field returns null, and your warehouse fills with nulls. Stage two is loud but late: the query becomes invalid and the whole ingest breaks at 3am.

Put an introspection diff in CI. Fetch the schema on a schedule, store it as an artifact, and diff against the last known good version. Fail the build on removals or type changes to fields your queries actually select, and warn on new deprecations. Tools in the Apollo and Hasura ecosystems ship schema-diff tooling for this, and rolling your own against the introspection result is not much work either. Either way, the point is that the check runs on a schedule rather than when the pager goes off.

The complementary habit is to keep queries narrow. Every field you select is a field that can break you, a field that costs budget, and a field that widens your Glue table. Selecting a whole object because it was convenient during development is a liability you carry indefinitely.

Wiring the GraphQL data ingestion pipeline on AWS

With the failure families understood, the AWS assembly is mostly a set of trade-offs about where the fetch loop lives.

Where the fetch loop runs

Step Functions can call an HTTPS endpoint directly with an HTTP Task, no Lambda involved. It uses an EventBridge connection to hold the credentials, which means your token lives in a Secrets Manager secret managed by EventBridge rather than in an environment variable:

"FetchPage": {
  "Type": "Task",
  "Resource": "arn:aws:states:::http:invoke",
  "Parameters": {
    "ApiEndpoint": "https://api.example.com/graphql",
    "Method": "POST",
    "InvocationConfig": {
      "ConnectionArn": "arn:aws:events:region:account-id:connection/name/id"
    },
    "Headers": { "Content-Type": "application/json" },
    "RequestBody": {
      "query.$": "$.query",
      "variables.$": "$.variables"
    }
  },
  "Retry": [{
    "ErrorEquals": [
      "States.Http.StatusCode.429",
      "States.Http.StatusCode.502",
      "States.Http.StatusCode.503",
      "States.Http.StatusCode.504"
    ],
    "IntervalSeconds": 1,
    "BackoffRate": 2,
    "MaxAttempts": 3,
    "JitterStrategy": "FULL"
  }],
  "Next": "InspectBody"
}

The execution role needs four permissions: states:InvokeHTTPEndpoint, events:RetrieveConnectionCredentials, and both secretsmanager:GetSecretValue and secretsmanager:DescribeSecret scoped to the EventBridge-managed secret.

It’s a clean pattern, and I like it for small, high-value syncs. Two constraints decide whether it fits. HTTP Task requests time out after 60 seconds, which a deeply nested GraphQL query can exceed without being pathological. And Step Functions reads the response within its standard state payload ceiling of roughly 256 KB, so a page of a hundred rich records will not fit. Also note the retrier above: it fires on HTTP status codes, so it will not catch a throttle that arrives as a 200 with an error in the body. That check has to happen in the state after it.

The alternative is a Lambda driver that paginates internally and writes pages straight to S3, returning only the cursor and a count to the state machine. This dodges both limits, gives you a real HTTP client with real backoff, and keeps large payloads out of the workflow’s state. It costs you per-page retry granularity, which you buy back with the checkpoint record.

Distributed Map is worth mentioning for the fan-out case, such as one child execution per tenant or per shard. It gives you high concurrency and a per-item execution history, which is genuinely useful for debugging. Be aware of two things before committing: express child workflows cap at five minutes rather than Lambda’s fifteen, and practitioners have published benchmarks showing throughput well below what the headline concurrency numbers suggest for small, fast items. For a lot of ingestion work, SQS plus a DynamoDB job table remains the simpler answer.

One case genuinely falls outside serverless: sources that require a long-lived session, a persistent websocket subscription, or a synchronisation window longer than fifteen minutes with no resumable cursor. A small always-on worker on a modest VPS from a provider like InterServer or Hetzner, feeding the same S3 landing zone, is less clever and more honest than contorting Lambda around the constraint.

The landing zone

Land raw responses first, unmodified, including the errors and extensions keys. Storage is the cheapest thing in this architecture and the raw layer is what lets you reprocess after you discover a parsing bug six weeks later.

• Partition by ingest time, not event time. Event-time partitioning requires reading the record before you know where to put it, which means you can’t write until you’ve parsed. Ingest-time keys let the raw write be dumb and fast.
• Put the run identifier in the key. When you need to unwind one bad run, being able to delete or ignore by prefix beats writing a surgical delete.
• Define Glue tables explicitly rather than crawling. You wrote the selection set, so you already know the schema. A crawler inferring types from JSON will surprise you the first time an optional field is absent from an entire page.
• Convert to columnar in the curated layer. Athena over raw JSON works and is fine for debugging. Parquet is what you want for anything anyone queries repeatedly.

If your source pushes rather than being polled, such as webhook deliveries carrying GraphQL payloads, Amazon Data Firehose (renamed from Kinesis Data Firehose, with APIs and IAM policies unchanged) will buffer, convert to Parquet and partition on the way to S3 without you running a consumer. For scheduled pull-based syncs it adds a hop you don’t need.

Troubleshooting

• Runs succeed but a column is all null. Field errors. Pull a raw response from the landing zone and look at the errors array. The path tells you exactly which field.
• Runs succeed but ingest zero rows. Likely a throttle returned as a 200. Log the response body and the rate-limit headers on empty results, always.
• Intermittent failures partway through pagination. Cursor expiry. Fall back to the watermark and check whether the source documents a cursor lifetime.
• Query fails immediately with no data key. Request error. Validate against current introspection; something in the schema moved.
• Throttled despite staying under the documented limit. Either concurrent workers are sharing a bucket they each think they own, or you’re being charged requested cost on near-empty pages.
• HTTP Task fails on large pages. The response exceeds the state payload ceiling. Reduce page size or move the fetch into Lambda.
• Row counts drift upward over time. Overlap without deduplication. Check that the curated layer actually resolves on the primary key.

Common mistakes

• Treating a 200 as success and never reading the body.
• Retrying request errors. They are deterministic; retrying just spends budget to fail identically.
• Hardcoding bucket sizes and restore rates that differ per plan tier and change without notice.
• Checkpointing the cursor before the data is durable.
• Requesting the maximum page size on every call while being charged the worst-case cost for it.
• Selecting entire objects because it was easier during development.
• Alerting only on execution failure, so a job that succeeds while ingesting nothing never pages anyone.
• Overlapping restart windows with no downstream deduplication.

Best practices

• Classify every response into clean, partial, or request-failed before anything downstream sees it.
• Persist raw responses with errors and extensions intact, then parse from the raw layer.
• Alarm on row-count deltas and partial-error rate, not just on execution status.
• Read the throttle state the API hands you and back off before you hit the wall, not after.
• Keep both a cursor and a watermark, and know which one is authoritative on restart.
• Diff the schema on a schedule so deprecations reach you before they reach your data.
• Hold credentials in Secrets Manager or an EventBridge connection, never in a Lambda environment variable.
• Trace the pipeline end to end. CloudWatch covers the basics; Grafana or Datadog earn their keep once you’re correlating child executions across a fan-out.

Frequently asked questions

Can Step Functions call a GraphQL API without a Lambda function?

Yes. An HTTP Task using the arn:aws:states:::http:invoke resource posts your query directly, with an EventBridge connection handling authentication. It works well for small pages. The 60-second request timeout and the state payload size ceiling are what push most real ingestion work back into Lambda.

How do I detect GraphQL errors when the status code is always 200?

Inspect the body. If there’s no data key, nothing executed and you have a request error. If data is present alongside a non-empty errors array, you have a partial response and the data is incomplete. Only a response with data and no errors is unambiguously clean.

Does AWS AppSync fit into this?

Only if you’re on the serving side. AppSync is a managed GraphQL API for exposing your own data, so it’s what you’d reach for if you wanted clients to push events in via mutations. For pulling data out of somebody else’s GraphQL API, AppSync isn’t part of the picture.

Should I store raw GraphQL responses or parsed records in S3?

Both, in separate layers. Raw responses are your audit trail and your reprocessing path, and they’re the only way to answer “was this field null in the source, or did my parser drop it?” weeks after the fact. Parsed and columnar output goes in a curated prefix that analysts query.

How do I run an incremental sync from a GraphQL API?

Find the schema’s filter argument for a modification timestamp using introspection, pass your stored watermark into it, and page forward with cursors. Overlap the window slightly on each run and deduplicate on the primary key downstream. If the schema exposes no such filter, you’re limited to full pulls or webhook-driven change capture.

Why am I throttled when I’m making very few requests?

Cost-based APIs charge for query complexity, not call count. A single deeply nested query pulling a connection inside a connection can consume a large fraction of the bucket by itself. Read the cost figures the API returns and flatten the query if the requested cost is consistently much higher than the actual cost.

Is GraphQL a worse ingestion source than REST?

Different, not worse. You control the payload, which cuts transfer and lets you avoid the N+1 fan-out REST forces on nested data. Deprecation metadata is machine-readable, which REST rarely offers. The cost is that error signalling and rate limiting both moved into the body, so naive clients fail silently instead of loudly.

The one thing worth remembering

A GraphQL data ingestion pipeline on AWS fails differently from a REST one, and the difference is almost entirely about where the truth lives. In REST, the transport tells you what happened. In GraphQL, the transport tells you the request arrived, and the body tells you what happened. Every failure family in this post traces back to that: partial errors hidden behind a 200, throttles hidden behind a 200, cursors that fail by returning the wrong rows rather than an error.

So build the pipeline so that a green run means something. Parse before you commit, alarm on row deltas rather than exit codes, and keep the raw responses so you can prove what the source actually said. Everything else is ordinary AWS plumbing.

Need help with a GraphQL ingestion pipeline?

This is the kind of work I take on regularly. Specifically:

• Auditing an existing GraphQL sync for silent partial-error loss and telling you which columns are already affected
• Building the fetch, checkpoint and land loop in Step Functions and Lambda with cursors that survive restarts
• Fitting a cost-aware throttle to whatever budget model your source actually uses, including multi-worker coordination
• Designing the raw and curated S3 layout, Glue table definitions and Athena partitioning so queries stay cheap
• Adding introspection diffing to CI so schema deprecations surface in a pull request, not in a dashboard
• Wiring CloudWatch metrics and alarms on row-count deltas and partial-error rates, so a green run is actually green

Send me a run log, a state machine definition, or a raw response with an errors array in it, and I’ll tell you what it’s costing you.

The post Building a GraphQL Data Ingestion Pipeline on AWS That Doesn’t Lie to You appeared first on John Nessime.