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

On this page
  1. The error body
  2. Status codes
  3. Rate limits
  4. Retrying safely
  5. Too many failed sign-ins

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"}
  • error is a short, stable code your program can check.
  • detail is 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 409 that says the same request is still running: wait a moment and retry.
  • Use Idempotency-Key when 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.