# API Error Codes and Quotas

## Rate limits {#rate-limit}

V2 REST requests and Admin MCP tool calls share organization-level rate limits and daily quotas. Switching keys, members or transports within the organization uses the same allowance. Operations have different rate and accounting rules. MCP initialization, ping and tool discovery do not consume business quota.

Send `{}` to `POST /api/v2/rpc/usage/get`, or call the MCP tool `usage_get`, to inspect usage, reservations, remaining quota and reset times. REST returns HTTP 429 for rate or quota limits. Check `data.error.code`. For `rate_limited`, wait for the returned `Retry-After` (seconds) or `retry_after_ms`. For `quota_exceeded`, check remaining quota and reset time. Retry writes with the original parameters and idempotency key.

For the default read and write rates and daily quotas by edition, see [Admin MCP and V2 REST limits](https://cli.im/open-api/en/start/quota-and-pricing.md#admin-mcp-and-v2-rest-limits).

## Top-level `code` (general)

- `0`: success
- `400`: invalid parameters or business error
- `401`: invalid API key (auth failed)
- `403`: credential type, authorization level or resource access is insufficient. See [permission troubleshooting](https://cli.im/open-api/en/openapi/v2/auth.md#verify-key)
- `404`: resource not found or no permission
- HTTP `429`: rate or quota limit. The V2 usage guard returns a string error code in the response body.
- `502`: upstream service unavailable

## Business `error_code`

When business errors occur, upstream may return `error_code`. The API passes it through to top-level `error_code` (along with top-level `code` and `message`).

Note: if upstream returns a non-`2xx` response that cannot be parsed, you may only see HTTP-layer errors such as `404/502`, and `error_code` may be absent.

Module error codes (`100300 ~ 100329`):

| error_code | message | Description |
|------------|---------|----------|
| `100300` | `System error` | System error (unclassified internal exception). |
| `100301` | `Invalid request parameters` | Invalid request parameters (missing required fields, wrong type, or illegal values). |
| `100302` | `Unsupported version` | Unsupported version (`version` cannot be recognized). |
| `100303` | `Record not found` | Record not found (`record_id` / `record_url` cannot locate a record). |
| `100304` | `Form not found` | Form not found (`tpl_id` cannot locate a form). |
| `100305` | `Unsupported output format` | Unsupported output format (`format` is invalid). |
| `100306` | `Form not assigned to this code` | The QR code is not associated with this form. |
| `100307` | `Duplicate submission not allowed for this field` | Duplicate submission not allowed (uniqueness check failed). |
| `100308` | `Required field is empty` | Required field is empty. |
| `100309` | `Field validation failed` | Field validation failed (format/content invalid). |
| `100310` | `Submitted resource has expired` | Dependent resource has expired. |
| `100311` | `User submission limit reached` | Per-user submission limit reached. |
| `100312` | `Form submission limit reached` | Form submission limit reached. |
| `100313` | `Submission not allowed at current time` | Submission is not allowed at current time. |
| `100314` | `Submission not allowed in current code state` | Submission is not allowed in current QR code state. |
| `100315` | `API key invalid or disabled` | API key is invalid or disabled. |
| `100316` | `API key org mismatch` | API key organization does not match request. |
| `100317` | `No codes found in the selected category` | No available QR codes in selected category. |
| `100318` | `Too many codes found in the selected category` | Too many QR codes matched (over system limit). |
| `100319` | `Certificate verification failed` | Generic certificate verification failure. |
| `100320` | `Invalid certificate code` | Invalid certificate code or target record not found. |
| `100321` | `Certificate verification is not enabled` | Verification is not enabled for the form/certificate. |
| `100322` | `Certificate record is not approved for verification` | Certificate record is not approved yet. |
| `100323` | `Certificate does not match the requested scope` | Certificate does not match `tpl_id` / `code_id` scope. |
| `100324` | `Certificate cannot be verified in current status` | Certificate cannot be verified in current status, or flow ended. |
| `100325` | `Invalid verification action` | Unsupported verification action or form configuration. |
| `100326` | `Invalid target certificate status` | Invalid target status, missing status, or no next status. |
| `100327` | `Invalid verification authorization code` | Verification authorization code invalid or expired. |
| `100328` | `No permission to verify this certificate` | Caller has no permission to verify this certificate. |
| `100329` | `Identity information required before verification` | Identity information must be completed before verification. |
