docs

REST API

Use Lymit from any language with one HTTP endpoint.

The SDK is a thin client over one endpoint. Any language can call it directly.

Authentication

Authorization: Bearer lym_live_… on every request. Missing, malformed, unknown or revoked → 401 invalid_api_key.

`POST https://api.lymit.io/v1/limit`

1curl -s https://api.lymit.io/v1/limit \2  -H "authorization: Bearer $LYMIT_API_KEY" \3  -H "content-type: application/json" \4  -d '{"namespace":"ai_generation","identifier":"user_123","cost":150,5       "config":{"algorithm":"tokenBucket","capacity":5000,"refillRate":1000,"interval":"1h"}}'

Body (≤ 4 KB):

Field	Type	Rules
`namespace`	string	1–256 chars
`identifier`	string	1–256 chars
`cost`	integer	≥ 0, default 1; 0 peeks
`config`	object	`{ algorithm: "fixedWindow" \| "slidingWindow", limit, window }` or `{ algorithm: "tokenBucket", capacity, refillRate, interval }`

Response — 200 allowed, 429 rejected — plus headers X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset (Unix seconds) and, on 429, Retry-After (seconds):

1{2  "success": true,3  "limit": 5000,4  "remaining": 4850,5  "reset": 1700000540000,6  "algorithm": "tokenBucket"7}

Errors

{ "error": { "code", "message", "field"? } }

Code	Status	When
`bad_request`	400	Invalid body; `field` names the culprit, e.g. `config.interval`
`invalid_api_key`	401	Missing, unknown or revoked key
`feature_not_in_plan`	403	e.g. `tokenBucket` on Hobby
`too_many_requests`	429	Workspace exceeded its per-minute ceiling
`quota_exceeded`	429	Workspace over its plan quota (distinct from a limit rejection by the presence of `error.code`)
`internal`	500	Our bug; details in our logs, never in the response

Codes are stable: we add, we never rename.