Skip to content
MentionBird.ai
Browse the documentation

Errors

Every failure comes back as JSON, including unexpected ones. You never get an HTML error page.

The error envelope

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "start_date must be YYYY-MM-DD."
  }
}

Read error.message. When a specific parameter is at fault the message names it, so a client can correct itself without guessing.

Status codes

400
Validation error — check the message in `error.message`.
401
Unauthorized — missing, invalid or revoked bearer token.
403
Forbidden — the plan lacks API access, the key is read-only, or addTrackedBrand would pass the tracked-brand limit.
404
Not found — the brand, prompt or resource does not exist.
405
Method not allowed.
429
Too many requests — over the key's per-minute or per-day limit. Wait the seconds in the `Retry-After` header, then retry.
500
Internal error — logged; retry is safe for reads.

A wrong value is an error, not an empty filter

If you send a value of the wrong type — say limit=many — you get a 400, not a 200 with the filter quietly dropped. That is deliberate: an answer that looks filtered but is not is worse than an error.

Leaving a parameter out, or sending it blank, still falls through to its default.

Not found means not found

A 404 covers both "this does not exist" and "this is not yours". We do not tell the two apart, so you cannot use the API to learn what another workspace holds.

Rate limits

Each API key can make 600 requests a minute and 10,000 a day. Both are fixed windows in UTC: the count starts again at the top of each minute and at midnight. An MCP client has its own allowance of the same size, per key or per sign-in.

Over the limit you get a 429. The Retry-After header gives the seconds to wait, and error.message says the same.

HTTP/1.1 429 Too Many Requests
Retry-After: 37

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Too many requests. Try again in 37 seconds."
  }
}

A request refused with a 429 still counts, so retrying before Retry-After has passed keeps you refused. So does one refused with a 403 because your plan doesn't include API access.

Retrying

Reads are safe to retry. A 500 is logged on our side. After a 429, wait the seconds in Retry-After first.

The write endpoints are safe to retry too. Repeating a call that already took effect changes nothing: adding something that already exists, archiving or restoring something already in that state, removing something already gone, or checking a brand that is already queued. A retry never creates a duplicate. A removal that went through is permanent, though, and retrying it cannot bring back what it deleted. Starting an agent run is the one write that can spend twice: a retry while the run is in progress returns that run, and a retry once a video is summarized returns the summary free, but a ranking-advice retry after its run finished starts a new run, and charges for it, when the prompt's sources have changed since.