Troubleshooting

Fresh

AWS Authentication Failures

Symptom: HTTP 403 Forbidden or UnrecognizedClientException

Common causes and fixes:

Credentials not set — Verify your environment variables are loaded:
bash
```
echo $AWS_ACCESS_KEY_ID
echo $AWS_SECRET_ACCESS_KEY
```
If empty, export them in your current shell session.
Wrong profile active — If using named profiles, confirm the correct profile is set:
bash
```
echo $AWS_PROFILE
aws sts get-caller-identity --profile imdb-api
```
Expired credentials — Temporary credentials (from STS, SSO, or assumed roles) expire. Refresh them through your identity provider.
Wrong region — The endpoint is in us-east-1. Ensure AWS_DEFAULT_REGION=us-east-1 is set or the region is passed explicitly in your SDK client.
IAM permissions missing — Your IAM user or role must have dataexchange:SendApiAsset permission and an active subscription for the resource.

Missing or Wrong Headers

Symptom: HTTP 400 Bad Request or MissingHeaderException

All five headers are required on every request. Missing any one of them will cause a 400 error:

Required Header	Check
`Content-Type: application/graphql`	Must be this exact value
`x-api-key`	From your Data Exchange subscription
`x-amzn-dataexchange-data-set-id`	From your Data Exchange subscription
`revision-id`	Must use the current revision
`asset-id`	From your Data Exchange subscription

If your revision has been updated by a new daily publish, the revision-id you have stored may be outdated. Retrieve the latest revision from the AWS Data Exchange console.

Wrong Endpoint

Symptom: HTTP 404 Not Found or connection errors

The endpoint must be exactly:

http://api-fulfill.dataexchange.us-east-1.amazonaws.com/v1

Common mistakes:

Using https:// — the endpoint uses http://
Wrong region in the URL (must be us-east-1)
Trailing slash missing on the path (/v1 not /v1/)
Sending a GET request instead of POST

JSON Parsing Errors

Symptom: SyntaxError: Unexpected token or malformed response

Query not wrapped in JSON — The request body must be {"query": "..."} with the GraphQL query as a string value
Unescaped quotes in inline queries — Use a .graphql file and readFileSync instead of hardcoding queries in strings
Response is a string, not parsed — The AWS SDK returns Body as a string. Parse it: JSON.parse(response.Body)
Error response in non-JSON format — If the API returns a text error (not JSON), your JSON.parse will fail. Log response.Body raw first to see the actual error message

Pagination Issues

Symptom: Only receiving the first page of results; subsequent pages return the same data or error

Missing after argument — Pass the endCursor from the previous page's pageInfo.endCursor as the after argument in the next request
Cursor expired or invalid — Cursors are stable for the duration of your session but should not be stored long-term. If a cursor returns an error, restart pagination from the beginning
Not checking hasNextPage — Always check pageInfo.hasNextPage before making another request. When it is false, you have all the results

graphql

# Correct pagination pattern
{
  title(id: "tt0068646") {
    principalCredits(filter: { categories: ["cast"] }) {
      credits(first: 10, after: "PASTE_END_CURSOR_HERE") {
        pageInfo {
          hasNextPage
          endCursor
        }
        edges {
          node {
            name { nameText { text } }
          }
        }
      }
    }
  }
}

Rate Limits

Symptom: HTTP 429 Too Many Requests

AWS Data Exchange enforces rate limits on API calls. If you hit the limit:

Implement exponential backoff: wait 1 second, then 2 seconds, then 4 seconds between retries
Batch multiple entity lookups into a single query using GraphQL aliases instead of making separate requests per title
Monitor your usage in AWS Cost Explorer to understand your call volume
Contact imdb-licensing@imdb.com if your use case requires higher throughput limits

Duplicate IDs

Symptom: A title or name ID returns data that doesn't match what you expect, or the response contains a remappedTo field

IMDb occasionally merges duplicate entries. When this happens:

The old ID remains but contains a remappedTo field pointing to the canonical ID
Always check the response for remappedTo before processing
If remappedTo is present, re-query using the canonical ID

graphql

{
  title(id: "tt9999999") {
    id
    # Check if this field is present in the response
  }
}

In bulk data processing, filter records where remappedTo is populated and redirect your processing to the target ID.

Empty or Missing Response Data

Symptom: Fields return null or are absent from the response

Subscription mismatch — Box office fields (productionBudget, lifetimeGross, etc.) require the IMDb and Box Office Mojo subscription. If you only have the Essential Metadata subscription, these fields will be empty
Field not populated for this title — Not every title has data for every field. A title that has no awards will not return any award data. This is expected behavior per the bulk data conventions (no null values — missing keys mean missing data)
Incorrect field name — GraphQL is case-sensitive. ratingsSummary not RatingsSummary. Check the field names against the sample queries
Querying an episode for series-level data — Some fields (like seriesInfo) only exist on series records, not episode records
Expired subscription — If your AWS Data Exchange subscription has lapsed, requests may return empty or partial data

Troubleshooting ​

AWS Authentication Failures ​

Missing or Wrong Headers ​

Wrong Endpoint ​

JSON Parsing Errors ​

Pagination Issues ​

Rate Limits ​

Duplicate IDs ​

Empty or Missing Response Data ​