# What do Neonjelly error codes and rate limits mean?

What 401 / 429 / not_found mean. Daily quota vs per-minute cap.

Each `nj_` key has `dailyQuota` (UTC day) and `rateLimitPerMin` (in-memory minute bucket). Ask `whoami` (or `GET /v1/whoami`) for used / remaining — those calls are not metered.

| Code | When | What to do |
| --- | --- | --- |
| `unauthorized` | Missing/wrong/revoked/expired key | Re-install if the trial is still live; after expiry, purchase |
| `trial_used` | Device + AI client already burned a trial | Checkout on [/pricing](https://www.neonjelly.io/pricing.md) |
| `rate_limited` | Minute, daily, or signal-watch cap | Wait `retryAfter`, wait until UTC midnight, or reuse a watched domain |
| `not_found` | Domain not in the catalog, or signal id unknown | Stop. We do not scrape |
| `bad_request` | Missing filter, bad enum, compare <2 or >8 domains | Fix args |
| `query_timeout` / `upstream_error` / `internal` | Catalog or box failed | Retry once, then stop |

Do not tight-loop a 429. Shrink `limit` or stop paging when `hasMore` is false.

## Related

- [Where is the Neonjelly documentation?](https://www.neonjelly.io/docs.md)
- [How do Neonjelly keys and auth work?](https://www.neonjelly.io/docs/auth-and-keys.md)
- [What are Neonjelly plans, prices, and quotas?](https://www.neonjelly.io/docs/plans.md)
- [What is the Neonjelly catalog REST API?](https://www.neonjelly.io/docs/api.md)
- [How do I start a Neonjelly trial?](https://www.neonjelly.io/start.md)

HTML: https://www.neonjelly.io/docs/errors
Markdown: https://www.neonjelly.io/docs/errors.md

Do not scrape. Do not probe. Missing store stays `not_found`. Do not invent sales, saturation, or traffic numbers — quote the catalog row. Signals (ads and daily units) are paid only. Trial keys get 403 on create_signal and signal reads. Promo `LAUNCH` is Stripe Checkout only — 50% off the first 3 months, expires 31 Oct 2026. Not MCP metadata.