What causes "monitor API key is required" in badges/shields?

Add the monitorKey query parameter to the badge URL.

badges/shields · error · InvalidParameter

monitor API key is required

Error message

monitor API key is required

What it means

UptimeObserver's ensureIsMonitorApiKey throws InvalidParameter when the monitorKey query parameter is empty or missing. It is a guard that runs before any HTTP request is made, so the badge cannot be rendered without credentials. The message means: you supplied no API key at all (a separate error covers keys that are too short).

Source

Thrown at services/uptimeobserver/uptimeobserver-base.js:22

const errorResponse = Joi.object({
  error: Joi.string().required(),
}).required()

const monitorResponse = Joi.object({
  status: Joi.string().required(),
  uptime24h: Joi.number().min(0).max(100).required(),
  uptime7d: Joi.number().min(0).max(100).required(),
  uptime30d: Joi.number().min(0).max(100).required(),
}).required()

const singleMonitorResponse = Joi.alternatives(monitorResponse, errorResponse)

export default class UptimeObserverBase extends BaseJsonService {
  static category = 'monitoring'

  static ensureIsMonitorApiKey(value) {
    if (!value) {
      throw new InvalidParameter({
        prettyMessage: 'monitor API key is required',
      })
    } else if (value.length <= 32) {
      throw new InvalidParameter({
        prettyMessage: 'monitor API key is unvalid',
      })
    }
  }

  async fetch({ monitorKey }) {
    this.constructor.ensureIsMonitorApiKey(monitorKey)

    // Docs for API: https://support.uptimeobserver.com/shields-api.yaml
    const url = `https://app.uptimeobserver.com/api/monitor/status/${monitorKey}`

    const response = await this._requestJson({
      schema: singleMonitorResponse,
      url,

View on GitHub (pinned to 766fd8bc89)

Solutions

Add the monitorKey query parameter to the badge URL.
Copy the monitor API key from your UptimeObserver account settings.
Check the build/config that generates the badge URL to ensure the key variable is populated.

Example fix

// before
https://img.shields.io/uptime-observer/status/12345
// after
https://img.shields.io/uptime-observer/status/12345?monitorKey=your64charkey

Defensive patterns

Strategy: validation

Validate before calling

if (!monitorKey) throw new Error('monitorKey query parameter is required')

Type guard

const hasKey = (v) => typeof v === 'string' && v.length > 0

Try / catch

try { await fetchBadge() } catch (e) { if (e instanceof InvalidParameter) console.error('monitorKey missing'); throw e }

Prevention

Keep the monitorKey in a config/env value and assert it is set before building URLs.
Never hand-edit badge URLs without re-checking query parameters.
Template badge URLs so the key is injected, never pasted piecemeal.

When it happens

Trigger: Fetching an uptime-observer badge without a monitorKey query parameter, or with an empty string (monitorKey=''), from the fetch() method which calls ensureIsMonitorApiKey.

Common situations: Copying a badge snippet and deleting the ?monitorKey= part; building the badge URL programmatically and the key variable being undefined due to an unset environment variable or config placeholder.

Understand the failure class

Background: "API key is required" / "API key not found" / "No API key was set": the missing-api-key error family across 16 libraries — this error's family across 16 libraries.

Related errors

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