Errors & limits
Stable lit.onl API error codes, HTTP status mapping, and rate-limit defaults for public REST, dashboard, and MCP so clients can retry and show clear messages.
JSON errors:
{
"error": "slug_taken",
"message": "That slug is taken"
}error | HTTP | When |
|---|---|---|
unauthorized | 401 | Missing or invalid OAuth access token |
insufficient_scope | 403 | Token missing a required scope |
upgrade_required | 403 | Plan too low (API and MCP are Growth+) |
slug_taken | 409 | Custom slug in use |
validation | 400 | Bad URL, expiry, CSV row |
not_found | 404 | Unknown link or webhook |
rate_limited | 429 | Burst exceeded |
payload_too_large | 413 | CSV over 5000 rows or body too big |
Rate limits
Sliding windows. Over limit → 429 with Retry-After (seconds).
| Surface | Limit |
|---|---|
| Auth login / register (per IP) | 10 / minute |
REST /v1 (Growth) | 60 / minute per OAuth client |
REST /v1 (Premium) | 600 / minute per OAuth client |
| MCP | Same as REST tier (60 Growth / 600 Premium per minute) |
| Public document unlock (per IP) | 30 / minute |
| Public document events (per IP) | 120 / minute |
Dashboard session routes have no separate quota; API keys and MCP share the REST limits above.
message is human; error codes stay English.