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.