Security & Limits

Rate limits, query guardrails, batch size limits, and HTTP error codes. All limits are enforced per-org based on plan tier.

Rate Limits

Token bucket algorithm, enforced at the API layer before requests hit storage or queues.

	Baby Monkey	Chimp	Mandrill	Silverback
Requests / sec	10	25	100	1,000
Burst	50	125	500	5,000
MonkeyTasks runs / sec	5	10	50	500
MonkeyBuckets uploads / min	10	25	100	1,000

Rate limit response

When limits are exceeded, the API returns 429 Too Many Requests with retry headers:

http

HTTP/1.1 429 Too Many Requests
Retry-After: 2
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1708387200

Note: The SDK automatically retries 429 responses with exponential backoff (1s → 2s → 4s, max 3 retries). If retries are exhausted, a MonkeyRateLimitError is thrown.

Query Guardrails

Max limit enforcement

If you request limit: 10000, the API overrides it to limit: 100 and returns a cursor for pagination.

Scan protection

Queries with only a filter and no key are rejected with 400 Bad Request. This prevents accidental full-table scans.

Item size limit

Items exceeding 400 KB are rejected with 413 Payload Too Large.

Batch Size Limits

Operation	Max per call	SDK behavior
MonkeyDB save()	25 items	Auto-chunks larger batches
MonkeyDB find()	100 keys	Auto-chunks larger batches
MonkeyTasks run()	10 tasks	Enforced (no auto-chunking)

Capacity Enforcement

When an org exceeds bundled monthly usage:

Plan	Behavior
Baby Monkey	Hard stop on request-path usage counters
Chimp	Soft limit — starter paid tier with overage billed at period end
Mandrill	Soft limit — overage billed per feature at period end
Silverback	Soft limit — higher bundled usage and the same per-feature overage model

File Storage Limits

	Baby Monkey	Chimp	Mandrill	Silverback
Max file size	50 MB	250 MB	500 MB	5 GB
Max files / bucket	1,000	10,000	100,000	Unlimited
Total file storage	500 MB	5 GB	25 GB	500 GB

HTTP Error Codes

Code	Meaning	When
400	Bad Request	Scan query without key, malformed payload
401	Unauthorized	Missing API key
402	Payment Required	Free tier bundled usage exhausted
403	Forbidden	Invalid API key or mk_pub_ used for write
404	Not Found	Item, job, or file does not exist
409	Conflict	Duplicate task ID
413	Payload Too Large	Item > 400KB or file > plan max size
429	Too Many Requests	Rate limit exceeded
500	Internal Server Error	Unexpected failure
503	Service Unavailable	Underlying storage throttling (temporary)