listings_limit_exceeded
Activating or creating a listing would take the workspace over its plan. Nothing else is blocked. Deactivate another listing first, or upgrade.
When it fires
A call would take the workspace over its plan's active-listing limit, so that one call was refused and nothing changed. Only three calls can do that:
PATCH /v1/listings/{id}with{"active": true}POST /v1/listings/statuswith"active": true(only listings that are currently inactive count toward the new total)POST /v1/listings(creating a listing)
Being over the plan never blocks your other calls. When a connection brings in more listings than the plan includes, the extra ones are held back: they stay connected and keep syncing, but they are not served. A held-back listing answers 403 listing_inactive and collections leave it out. Every JSON response then carries a planNoticesaying how many are held back. On Free it also gives Starter's price today (starterMonthlyPrice for your starterListings active listings, what checkout charges) and a checkoutUrl that opens Starter checkout. Upgrading does not switch held-back listings on: choose which to activate afterwards, in Billing or with POST /v1/listings/status. Starter is $99 a month with 10 listings included, then $5 a month per listing from the 11th to the 100th.
Active listings by plan:
| Plan | Active listings |
|---|---|
free | 3 |
starter | No cap. 10 included, then billed per listing ($5 for 11–100, $3 for 101–150, $2 for 151–300, $1.50 for 301–500, $1 for 501–1,000, $0.70 above) |
custom | No cap |
The error tells you where you stand: tier is the current plan, limit is the number of active listings it includes, and active_listings is the live count.
Response shape
Every Repull error follows the same envelope. The code is stable and safe to switch on.
{
"error": {
"code": "listings_limit_exceeded",
"message": "Reactivating this listing would put you at 4 active listings, but the 'free' tier is capped at 3.",
"fix": "Deactivate another listing first (DELETE /v1/listings/{id} or PATCH with { \"active\": false }), or upgrade your plan at https://repull.dev/dashboard/billing to lift the cap.",
"docs_url": "https://repull.dev/docs/errors/listings_limit_exceeded",
"tier": "free",
"limit": 3,
"active_listings": 3,
"upgrade_url": "https://repull.dev/dashboard/billing",
"request_id": "req_01HXY..."
}
}How to fix
- Read `error.limit` and `error.active_listings`: the gap is how many listings you can still activate (often 0).
- Path A: choose which listings are active. Deactivate one you do not need with `POST /v1/listings/status` `{"listingIds": [...], "active": false}` or `PATCH /v1/listings/{id}` `{"active": false}`, then activate the one you want. Deactivated listings keep syncing and can be activated again later.
- Path B: upgrade at `https://repull.dev/dashboard/billing` (also in `error.upgrade_url`). Starter has no listing cap. The usage cache is 60 seconds, so the first activation after an upgrade may take up to a minute.
- Do not retry the same call in a loop. Unlike 429 there is no `Retry-After` and nothing to wait for. Your other calls are not affected.
Common gotchas
- Nothing else is blocked. Reservations, messaging, pricing, Connect, billing and every other workspace keep working while you are at or over the limit. Only the activating or creating call gets the 402.
- 402 is not 429. There is no
Retry-After. Switch onerror.codeand show the user a choice (deactivate another listing, or upgrade) instead of retrying. - Over the plan after a downgrade. If a workspace has more active listings than its plan includes (for example after a plan ends), calls are still served and
planNoticeuses the codelistings_over_plan. Choose which listings stay active withPOST /v1/listings/status, or upgrade. - The limit is on active listings. Inactive and held-back listings do not count, even though their data keeps syncing. See Active & inactive listings.
- Starter and custom have no listing cap, so this error is never returned to them.
Examples
curl
# A free workspace with 3 active listings tries to activate a 4th
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": ["4120"], "active": true }'
# HTTP/1.1 402 Payment Required
# { "error": { "code": "listings_limit_exceeded", "limit": 3, "active_listings": 3, ... } }
# Swap: deactivate one, then activate the one you want
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"], "active": false }'
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": ["4120"], "active": true }'
# HTTP/1.1 200 OK
# Everything else keeps working the whole time
curl https://api.repull.dev/v1/reservations -H "Authorization: Bearer sk_live_FREE_TIER_KEY" # 200TypeScript
const API = 'https://api.repull.dev'
const headers = {
Authorization: `Bearer ${process.env.REPULL_API_KEY}`,
'Content-Type': 'application/json',
}
async function activate(listingIds: string[]) {
const res = await fetch(`${API}/v1/listings/status`, {
method: 'POST',
headers,
body: JSON.stringify({ listingIds, active: true }),
})
if (res.status !== 402) return res.json()
const { error } = await res.json()
if (error.code !== 'listings_limit_exceeded') throw new Error(error.message)
// Nothing was activated, and nothing else is blocked. Ask the user:
// deactivate another listing to make room, or upgrade (Starter has no cap).
return {
needsChoice: true,
room: Math.max(0, error.limit - error.active_listings),
upgradeUrl: error.upgrade_url,
message: error.message,
}
}If you're an AI agent
This call would take the workspace over its plan's active-listing limit, so it was refused and nothing changed. Only activating (PATCH /v1/listings/{id} {active:true}, POST /v1/listings/status {active:true}) or creating a listing (POST /v1/listings) can return this; every other call keeps working. Do not retry in a loop. Tell the user the plan's limit (error.limit) and offer two paths: deactivate another listing first with POST /v1/listings/status {listingIds, active:false}, or upgrade at error.upgrade_url (Starter has no listing cap; it is billed per listing).
Related
- Error reference — the full table of error codes
- Using Repull from AI agents — patterns for handling errors in agent loops
- Active & inactive listings
- Credits and usage
- Rate Limits
- listing_inactive (403)
- rate_limited (429) — the wait-and-retry sibling
Hit an error that isn't covered? Email hello@repull.dev with the request id from the response headers.