<p class="crumbs"><a href="/docs/">Docs</a></p>

# Errors

Errors look like this:

```json
{
  "code": "insufficient_balance",
  "message": "This call costs 0.02 USD",
  "message_zh": "余额不足",
  "request_id": "req_…",
  "charged": false,
  "retry": "no",
  "retry_after_seconds": null,
  "docs": "https://feedmcp.com/docs/errors/#insufficient_balance",
  "top_up_url": "https://feedmcp.com/console/top-up/"
}
```

`retry` values: `no`, `yes`, `once` (retry once later), `after_fix` (fix the request first), `same_key` (retry with the same Idempotency-Key).

| code | HTTP | Meaning | retry | Charged |
| --- | --- | --- | --- | --- |
| <a id="invalid_params"></a>`invalid_params` | 400 | The parameters are not valid | `after_fix` | No |
| <a id="price_above_max"></a>`price_above_max` | 400 | The price of this call is above your X-Max-Price | `after_fix` | No |
| <a id="unauthorized"></a>`unauthorized` | 401 | Missing or invalid API key | `after_fix` | No |
| <a id="insufficient_balance"></a>`insufficient_balance` | 402 | Insufficient balance | `no` | No |
| <a id="key_spend_cap_reached"></a>`key_spend_cap_reached` | 402 | This key has reached its spend cap | `no` | No |
| <a id="forbidden"></a>`forbidden` | 403 | Not allowed | `no` | No |
| <a id="not_found"></a>`not_found` | 404 | The object does not exist, was deleted or is not visible | `no` | No |
| <a id="video_too_long"></a>`video_too_long` | 422 | The video is longer than two minutes; on this platform only videos up to two minutes can be transcribed | `no` | No |
| <a id="unknown_endpoint"></a>`unknown_endpoint` | 404 | There is no such endpoint | `no` | No |
| <a id="idempotency_conflict"></a>`idempotency_conflict` | 409 | This Idempotency-Key was used for a different request | `after_fix` | No |
| <a id="rate_limited"></a>`rate_limited` | 429 | Too many calls | `yes` | No |
| <a id="upstream_error"></a>`upstream_error` | 502 | The platform could not be read just now | `once` | No |
| <a id="free_quota_paused"></a>`free_quota_paused` | 503 | Today's free trial capacity is used up and returns tomorrow; accounts with a balance are not affected | `yes` | No |
| <a id="upstream_timeout"></a>`upstream_timeout` | 504 | The platform took too long to answer | `same_key` | No |
| <a id="internal_error"></a>`internal_error` | 500 | Internal error | `same_key` | No |

---

HTML version: https://feedmcp.com/docs/errors/
