# API limits and errors

> How to make reliable requests to the ListBulb REST API.

Canonical: https://www.listbulb.com/docs/api/reference
Last updated: 2026-11-22

## Rate limits

| Scope | Limit | Applies to |
| --- | --- | --- |
| Catalog reads | 60 / minute | Per IP address. |
| Private drafts | 10 / 24 hours | Per active API key. |

When a limit is reached, the API returns `429 RATE_LIMITED` and a `Retry-After` header in seconds. Wait for that duration before retrying.

## Errors

Every error has the same shape: `{ error: { code, message } }`.

- `400` - invalid query, slug, JSON, or request body.
- `401 API_KEY_REQUIRED` - the draft endpoint needs an active personal key.
- `404 TOOL_NOT_FOUND` - the requested product is absent or not public.
- `409 IDEMPOTENCY_CONFLICT` - an idempotency key was reused with different request data.
- `429 RATE_LIMITED` - retry after the supplied delay.
- `503 RATE_LIMIT_UNAVAILABLE` - draft creation is temporarily paused because its limit store is unavailable.

## Retry safely

Use one unique `Idempotency-Key` per draft. If the network drops after sending the request, retry with that exact key and unchanged body; ListBulb returns the original draft instead of creating another one.
