listings_limit_exceeded

{
  "error": {
    "code": "listings_limit_exceeded",
    "message": "Your account has 24 active listings but the 'free' tier is capped at 3...",
    "fix": "Either reduce your active listings to 3 or fewer (via DELETE endpoints — these are still served), or upgrade your plan at https://repull.dev/dashboard/billing to lift the cap immediately.",
    "docs_url": "https://repull.dev/docs/errors/listings_limit_exceeded",
    "tier": "free",
    "limit": 3,
    "active_listings": 24,
    "upgrade_url": "https://repull.dev/dashboard/billing",
    "request_id": "req_01HXY..."
  }
}

# Over-cap free-tier workspace calling any non-DELETE endpoint
curl https://api.repull.dev/v1/listings \
  -H "Authorization: Bearer sk_live_FREE_TIER_KEY"

# HTTP/1.1 402 Payment Required
# {
#   "error": {
#     "code": "listings_limit_exceeded",
#     "message": "Your account has 24 active listings but the 'free' tier is capped at 3...",
#     "fix": "Either reduce your active listings to 3 or fewer (via DELETE endpoints — these are still served), or upgrade your plan at https://repull.dev/dashboard/billing to lift the cap immediately.",
#     "docs_url": "https://repull.dev/docs/errors/listings_limit_exceeded",
#     "tier": "free",
#     "limit": 3,
#     "active_listings": 24,
#     "upgrade_url": "https://repull.dev/dashboard/billing",
#     "request_id": "req_01HXY..."
#   }
# }

# Recovery path A — deactivate listings (served over-cap, still 200s)
curl -X POST https://api.repull.dev/v1/listings/status \
  -H "Authorization: Bearer sk_live_FREE_TIER_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "listingIds": ["4118", "4119"], "active": false }'

# Recovery path B — upgrade and wait for the 60s usage cache to refresh
open https://repull.dev/dashboard/billing
# … wait ~60s …
curl https://api.repull.dev/v1/listings \
  -H "Authorization: Bearer sk_live_FREE_TIER_KEY"
# HTTP/1.1 200 OK

# Allowlist — these continue to work over-cap
curl https://api.repull.dev/v1/health        -H "Authorization: Bearer ..."   # 200
curl https://api.repull.dev/v1/usage/tier    -H "Authorization: Bearer ..."   # 200

import { Repull } from '@repull/sdk'

const repull = new Repull({ apiKey: process.env.REPULL_API_KEY! })
const API = 'https://api.repull.dev'
const headers = {
  Authorization: `Bearer ${process.env.REPULL_API_KEY}`,
  'Content-Type': 'application/json',
}

// RepullError (thrown by the SDK) carries code, message, fix and docsUrl, but
// not tier / limit / active_listings / upgrade_url. Read the envelope directly
// when you need those numbers.
const res = await fetch(`${API}/v1/reservations`, { headers })

if (res.status === 402) {
  const { error } = await res.json()
  if (error.code !== 'listings_limit_exceeded') throw new Error(error.message)

  // 402 — NOT a "wait and retry" condition. Do not back off.
  // Two paths back to 200:
  //   1. Deactivate listings until active_listings <= limit
  //   2. Upgrade at error.upgrade_url
  console.error(
    `Over plan cap: ${error.active_listings} active / ${error.limit} on the '${error.tier}' tier.`,
  )

  const overflow = error.active_listings - error.limit
  if (overflow < 5) {
    // Path A — deactivate a few listings. GET /v1/listings and
    // POST /v1/listings/status are both served over-cap.
    const { data: listings } = await repull.listings.list({ limit: overflow })
    // One all-or-nothing call instead of a DELETE per listing.
    await fetch(`${API}/v1/listings/status`, {
      method: 'POST',
      headers,
      body: JSON.stringify({ listingIds: listings.map((l) => l.id), active: false }),
    })
  } else {
    // Path B — surface the upgrade URL to the operator
    return { needsUpgrade: true, upgradeUrl: error.upgrade_url, message: error.message }
  }
}