Reference
Status codes
Every error response is JSON with an error string. The message distinguishes the four different reasons for a 429, which is the one you are most likely to handle.
| Code | What happened | What to do |
|---|---|---|
| 400 | The body was not valid JSON, or a required field was missing or malformed. | Check botId and question are present, and that url on ingest is a full http(s) address. |
| 401 | The Authorization header was missing, malformed, or the key is not valid. | Send Authorization: Bearer mc_sk_… with a key from Account → API keys. |
| 403 | The workspace's plan does not include API access. | API access is an Agency plan feature. Checked per request, so a plan change takes effect immediately. |
| 404 | No active bot with that id belongs to your workspace. | Confirm the bot id and that the bot is active. Ids are scoped to your workspace, so another workspace's id reads as unknown. |
| 429 | A rate limit, daily cap, or monthly allowance was reached. The message says which. | See Rate limits below — each of the four has a different remedy. |
| 500 | The request was valid but could not be completed. | Safe to retry once. If it persists, get in touch rather than retrying in a loop. |
A 429 is not always a rate limit. It is also returned when the bot has hit its daily cap, its daily message limit, or the workspace's monthly allowance — so back off and retry only when the message says the rate limit. The other three will not clear in a few seconds.