Docs / Errors & Rate Limits

Error contract and quota signaling

When to use

Use this when implementing retries and fallback

This contract is designed for autonomous clients that need deterministic recovery behavior.

Request example

Any MCP tool call

{
  "jsonrpc": "2.0",
  "id": "2",
  "method": "tools/call",
  "params": {
    "name": "create_video",
    "arguments": {
      "provider": "minimax",
      "prompt": "Aerial shot of a coastal city at sunrise"
    }
  }
}

Response example

Machine-readable denial payload

{
  "error": "quota_exceeded",
  "error_code": "quota_exceeded",
  "error_description": "quota_exceeded_hourly_calls",
  "actionable_next_step": "Throttle request rate and retry after the reset window.",
  "retryable": true
}

Error behaviors

How clients should react

  • • Respect retryable=false by escalating or changing strategy.
  • • For quota_exceeded, read Retry-After before retrying.
  • • For policy denials, switch to allowed tool tiers or trusted clients.

Operational notes

Header contract

RateLimit-Limit
RateLimit-Remaining
RateLimit-Reset
X-RateLimit-Limit
X-RateLimit-Remaining
X-RateLimit-Reset
Retry-After (on 429)