Errors and rate limits
What each error code means, how many requests you can make, and how to retry without doing things twice.
For developers
When a request can't be done, the Agent API answers with an HTTP status code and a short JSON body that says why. This page explains each one and how to handle it.
The error body
Most errors look like this:
{"error": "forbidden", "detail": "Permission denied: create_posts"}
erroris a short, stable code your program can check.detailis a sentence for people. Show it or log it, but don't match on its exact words — they can improve over time.
Two answers have a different shape:
- 401 (no key or a bad key) answers
{"detail": "Unauthorized"}. - 422 for a request that doesn't match the expected format (a missing field, a wrong type) lists every problem:
{"detail": [{"type": "missing", "loc": ["body", "payload", "caption"], "msg": "Field required"}]}.
Status codes
| Code | error |
What it means | What to do |
|---|---|---|---|
200 / 201 |
Done. 201 means something was created. |
||
202 |
Accepted and queued (for example a webhook redelivery). | ||
400 |
bad_request |
The request doesn't make sense, for example an empty reply. | Fix the request. |
401 |
No key, a wrong, revoked or expired key, or plain http://. |
Check the key and use https://. |
|
403 |
forbidden |
The key lacks a permission, the account isn't on its list, or the key's creator may not do this. detail names what's missing. |
Give the key the permission, or use another account. |
404 |
not_found |
It doesn't exist, or it's outside the key's workspace or accounts. | Check the id. |
409 |
conflict |
The network refused or the state doesn't allow it: the 24-hour reply window on Messenger, Instagram or WhatsApp closed, an account needs reconnecting, or the same request is still running. | Read detail. Don't retry blindly. |
413 |
storage_quota_exceeded |
The upload would go over the workspace's storage limit. | Free up space or upgrade the plan. |
415 |
unsupported_media_type |
That file type isn't accepted. | Use a supported image or video format. |
422 |
unprocessable_entity |
A value isn't valid, for example a time in the past, or an Idempotency-Key reused with a different body. |
Fix the value. |
429 |
rate_limited |
Too many requests. | Wait for Retry-After seconds. |
5xx |
Something went wrong on our side or at a network we talk to. | Retry later with a growing wait. |
A storage error carries extra fields (used_bytes, limit_bytes, attempted_bytes) and the headers X-Storage-Used, X-Storage-Limit and X-Storage-Remaining.
Rate limits
Limits keep one busy tool from slowing everyone down. They count per minute:
| Limit | Default |
|---|---|
| Reads per key (requests that only look things up) | 300 per minute |
| Writes per key (requests that change or send something) | 120 per minute |
| Writes per workspace, all keys together | 1,000 per minute |
Over a limit you get 429 with a body that says which limit (tier) you hit and when to try again:
{"error": "rate_limited", "tier": "per_key_writes", "limit": 120, "remaining": 0, "retry_after": 60}
The answer also has these headers. They only appear on 429 answers, not on every response:
| Header | What it says |
|---|---|
Retry-After |
Seconds to wait before trying again (the same number as retry_after). |
X-RateLimit-Limit |
The limit you went over (the same number as limit). |
X-RateLimit-Remaining |
What's left of it: 0 on a 429. |
Need higher limits for one key? Ask your Luminobot administrator.
Usage today
Settings → API keys shows, for each key, how many requests it made today (midnight to midnight UTC), how many of them were refused for going over a limit, and its per-minute limits. Requests through an AI assistant (MCP) that use the key count too. Your Luminobot administrator may also set a daily limit per key; the page then shows "1,200 of 5,000 requests today" and, over it, requests get 429 with tier per_key_daily and a retry_after that runs until midnight UTC. Every request counts toward it, refused ones included, so back off when you get a 429.
Daily posting limits per account
Each social account also has a rolling 24-hour limit on how many posts the API may add to it, set at or just below what the network itself allows. Posts that are scheduled, publishing, published or failed in the last 24 hours count — from the API and the app alike. Drafts don't count. For example: Instagram 25, TikTok 15, YouTube 50, LinkedIn 100, Pinterest 100, Facebook 200, Bluesky 200, Mastodon 200, Threads 250, Google Business 50, X 100 (X is also limited by your plan's monthly X posts). Over it, you get 429 with tier set to platform_quota:<network> and a retry_after that says when the oldest post stops counting.
AI assistants
AI assistant connections (MCP) have their own limit per connection: 120 requests per minute unless you set another number on the connection's page. Over it, the answer is 429 with tier per_connection. A connection can also have daily caps on messages sent and posts published — see Keeping AI agents safe.
Retrying safely
- 429: wait the number of seconds in
Retry-After, then try again. - 5xx, timeouts and network errors: retry after a short wait that grows each time (for example 1, 2, 4, 8 seconds, plus a little randomness), and give up after a few tries.
- Other 4xx: don't retry the same request — change it first. The one exception is a
409that says the same request is still running: wait a moment and retry. - Use
Idempotency-Keywhen you create a post, upload media or send a reply. If a retry reaches us after the first try already worked, you get the first answer back instead of a second post or a duplicate message. Use a new key for each new action.
curl -s -X POST https://app.luminobot.com/api/v1/inbox/messages/0b6c…/reply/ \
-H "Authorization: Bearer $BRAND_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: reply-0b6c-1" \
-d '{"text": "Hi Sam, yes, we are open on Sunday from 9 to 3."}'
Too many failed sign-ins
After 10 requests with a wrong key from the same internet address within a minute, further requests from that address are refused with 401 for the rest of that minute. Fix the key in your tool and the next minute works again.