Errors and limits

The error envelope, every error code, rate limits per plan and size limits for the REST API.

Error response

Every error is JSON with a code and a message.

{
  "error": {
    "code": "invalid_session",
    "message": "Session tokens are 8 to 128 characters."
  }
}

Branch on code. The message is written for a person, names the fix, and can change.

Status codes

Error codes

Credentials and requests

Messages and uploads

Keys, webhooks and tool endpoints

Organization and members

Inbox, knowledge, signals and tasks

Integrations

Not found

The 404 codes are conversation_not_found, customer_not_found, fact_not_found, knowledge_doc_not_found, knowledge_folder_not_found, suggestion_not_found, signal_not_found, commit_not_found, approval_not_found, invite_not_found, endpoint_not_found, tool_not_found, key_not_found, org_not_found, task_not_found and log_not_found, and any other code ending in _not_found, such as member_not_found, channel_not_found, role_not_found, team_not_found, repo_not_found and commit_repo_not_found. An id from another organization reads as not found.

Conflicts

Rate limits

Limits apply per organization. Every key, OAuth token, MCP session and assistant action in the organization draws from one allowance. Each class is a token bucket with a sustained rate per minute and a burst that can be spent at once.

Plan and add-on prices are in Plans.

What counts

• Each median.* call inside an MCP median_run counts as one request of its class.
• The assistant’s actions count the same way.
• A request is charged before it runs, so a request that fails afterwards still counts.
• POST /v1/organizations and POST /v1/me/organization always draw from a per-person allowance. GET /v1/me does too while the token has no organization, or its person has left it. The allowance is 600 reads a minute with a burst of 100, and 120 writes a minute with a burst of 30.

When you hit a limit

HTTP/1.1 429 Too Many Requests
retry-after: 3
content-type: application/json

{"error":{"code":"rate_limited","message":"Your organization's API allowance is temporarily full. Please retry shortly."}}

• Retry-After is in whole seconds, at least 1.
• Median can restrict an organization under fair use. The response is the same 429 rate_limited, with "reason": "fair_use" in error and “API access is temporarily limited to protect shared capacity. Please retry shortly.” or “API access is temporarily limited because unusual automated traffic was detected. Contact support for review.”
• Each refusal of the organization’s allowance is recorded in Logs as API limit reached.

Read your limits

curl https://api.median.sh/v1/billing/limits \
  -H "Authorization: Bearer $MEDIAN_KEY"

{
  "tier": "standard",
  "version": "2026-09-22",
  "limits": {
    "read": { "perMinute": 6000, "burst": 1000 },
    "write": { "perMinute": 1200, "burst": 300 },
    "upload": { "perMinute": 300, "burst": 100 }
  }
}

limits is null on unlimited. Any member can call it. The CLI is median billing limits. The dashboard shows the same numbers in Settings → Billing on the API limits row.

Other limits

These are separate buckets. A REST call that meets one is still charged to the tier as well.

• Adding a tool endpoint or changing its URL is not counted as a sync.
• Registration and device login also share a ceiling of 6,000 an hour across all callers.
• The REST buckets refuse with 429 rate_limited and “Too many requests. Wait a moment and try again.” The OAuth routes refuse with 429 and the OAuth error slow_down.

Size limits