badges/shields · info · NotFound

not found

Error message

not found

What it means

The iTunes/APP Store version service throws a generic NotFound when the iTunes lookup API responds with HTTP 200 but resultCount === 0 and an empty results array. iTunes signals 'not found' with a success status code rather than a 404, so the service must detect it from the body.

Source

Thrown at services/itunes/itunes.service.js:49

  }

  static defaultBadgeData = { label: 'itunes app store' }

  async fetch({ bundleId }) {
    return this._requestJson({
      schema,
      url: `https://itunes.apple.com/lookup?id=${bundleId}`,
    })
  }

  async handle({ bundleId }) {
    const data = await this.fetch({ bundleId })

    if (data.resultCount === 0) {
      // Note the 'not found' response from iTunes is:
      // status code = 200,
      // body = { "resultCount":0, "results": [] }
      throw new NotFound()
    }

    return renderVersionBadge({ version: data.results[0].version })
  }
}

View on GitHub (pinned to 766fd8bc89)

Solutions

  1. Verify the bundleId in the badge URL exactly matches the app's App Store bundle identifier
  2. Confirm the app is still publicly listed on the App Store (not region-locked or removed)
  3. If the app is region-restricted, query a country where it is available if the service supports it
  4. Remove the version badge for delisted apps

Example fix

// before
[![itunes](https://img.shields.io/itunes/v/bundle.id.wrong)]
// after (correct bundle id)
[![itunes](https://img.shields.io/itunes/v/com.example.myapp)]
Defensive patterns

Strategy: type-guard

Validate before calling

const data = await (await fetch(`https://itunes.apple.com/lookup?bundleId=${bundleId}`)).json()
if (!data || data.resultCount === 0) console.warn(`No App Store app found for bundleId ${bundleId}`)

Type guard

const hasResults = (data) => data != null && typeof data.resultCount === 'number' && data.resultCount > 0 && Array.isArray(data.results)

Try / catch

try {
  const version = await service.handle({ bundleId })
} catch (e) {
  if (e instanceof NotFound) {
    // iTunes returns 200 with resultCount:0 for missing apps
    // render 'not on App Store' badge
  } else throw e
}

Prevention

When it happens

Trigger: Requesting a version badge with a bundleId that does not exist on the App Store, an app that was pulled from the store, or a bundleId for a different platform/region than the one queried.

Common situations: App removed by Apple or by the developer; typo in the bundle identifier; app not available in the region used by the lookup; bundleId belongs to a beta/TestFlight build never publicly released.

Understand the failure class

Background: "Not found" and "does not exist" errors: why "Task not found", "No such folder", and "Can't find" fire when a lookup comes back empty — this error's family across 14 libraries.

Related errors

AI-assisted analysis of badges/shields@766fd8bc89 (2026-08-30). Data as JSON: /api/errors/bf9d2cc4f4f958a9. Report an issue: GitHub.