--- title: Limits and errors description: The MCP server's HTTP statuses, tool error codes, rate limits and per-call limits, and where they differ from the REST API. canonical: https://developers.coevera.com/ai/limits-and-errors/ section: ai publisher: Coevera --- # Limits and errors **Answer:** The MCP server answers 401 for a missing or expired token, 403 when the token lacks a scope, 422 for invalid input and 429 with Retry-After at a rate limit. It limits bursts per token and sustained use per space; the thresholds are not published. A 429 is plain HTTP, so an agent may report it as a transport failure. ## HTTP statuses The MCP server's [troubleshooting](https://mcp-server.coevera.com/doc#troubleshooting) section lists the same statuses. | Status | Meaning | What to do | | ------ | ----------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------- | | `401` | The token is missing, expired or malformed. | Sign in again. | | `403` | The token lacks a required scope. | Sign in again and approve all scopes. | | `406` | The request has no supported `Accept` header. | Send `Accept: application/json, text/event-stream`. | | `422` | Invalid input: bad filter syntax, an unknown field, a missing parameter. | Fix the arguments; `meta_describe_entity` lists the valid fields. | | `429` | A rate limit was hit. | Wait for the `Retry-After` seconds, then retry. | | `500` | An unexpected server error. | Retry later. | | `503` | Coevera could not be reached, or answered unexpectedly. The server has already retried 5 times, 30 seconds apart. | Retry later. | > **A 429 is not a tool error:** The `429` is sent as a plain HTTP response before the MCP layer, not as a tool result. Some > agents and clients report it as a transport or connection failure. If an agent stops with a > connection error during a burst of calls, check for a rate limit before anything else. ## Tool errors A tool that runs but cannot do its job returns an error result with one of these codes: `invalid_input`, `permission_denied`, `api_error`, `server_error`, `read_only_field_violation`, `missing_id`, `invalid_id`. Write tools report per record. `create_records` returns one result per input, in input order. `update_records` skips the invalid records and still submits the valid ones, so read every result, not only the first. - Writes are validated as in Coevera itself. A record that breaks a rule (a required field, a field value, a relation, a step checklist or a custom validation rule) comes back as an error for that record and is not stored, so the assistant can correct it. - `picture_id` on accounts, contacts and products cannot be written with `create_records` or `update_records`: they answer `read_only_field_violation` for that record and name `set_record_picture`. - A tool rejects an argument name it does not know, with an error that lists the valid names. ## Rate limits The server limits requests in two stages: a short burst limit per token and a longer sustained limit per space. Either answers `429` with `Retry-After`. The thresholds are not published. The API calls a space can make each month depend on its plan; see [coevera.com/crm/pricing](https://www.coevera.com/crm/pricing/). ## Per-call limits | Tool or endpoint | Limit | | ----------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `search_records` | `limit` up to 100 records per call | | `global_search` | A text of 2 to 200 characters; `limit` from 1 to 50, 20 by default | | `run_report` | Up to 10 metrics and 3 group-by fields; up to 500 groups (`limit_groups`, 50 by default). It reads at most `scan_cap` records (10,000 by default) within a time budget; `truncated` and `truncated_reason` say when the result covers only part of the matching records. | | `export_records` | Up to 100 fields, and at most `max_rows` rows per file (10,000 by default). The download link works once and expires after `expires_in_seconds` (10 minutes by default). | | `delete_records` | Up to 100 IDs per call. Leads and opportunities cannot be deleted; archive them. | | `bulk_move_opportunities`, `bulk_archive_opportunities`, `bulk_archive_leads` | Batches of 20 or more run asynchronously. | | `bulk_qualify_leads` | Runs synchronously at any batch size. | | File upload (`upload_cloud_object_document`, `set_record_picture`) | 50 MiB per file, given in `max_file_bytes`. The upload URL works once and expires after five minutes. A picture must be a PNG, JPEG, GIF or WebP image. | Long calls send progress notifications while they run, when the client accepts a stream. `run_report` and `export_records` share a few scan slots on each server worker. When all of them are busy, a call waits for a while and then gets a server-busy error; retry it later. ## Upload and download links The single-use links that the upload tools and `export_records` return answer with their own statuses. The two-step flow is in the [file upload reference](https://mcp-server.coevera.com/doc#upload). | Status | Upload link (`/upload/{token}`) | Download link (`/download/{token}`) | | ------ | ----------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- | | `200` | The file is stored; the body describes the document, or the record and its new picture. | The CSV file. | | `400` | The body could not be read. The link is used up. | Not returned | | `403` | Not returned | The user's role no longer allows exporting. | | `410` | The link expired or was already used. Call the tool again. | The link expired or was already used. Call the tool again. | | `413` | The file is larger than `max_file_bytes`. The link is used up. | Not returned | | `415` | `set_record_picture` only: the file is not a PNG, JPEG, GIF or WebP image. The link is used up. | Not returned | | `500` | Coevera refused the upload, for example a wrong folder or no write permission on documents. | Not returned | | `502` | Not returned | Coevera refused the request. | | `503` | All upload slots are busy: retry the same link after `Retry-After`. | All download slots are busy: retry the same link after `Retry-After`. | If Coevera fails partway through a download, the connection is cut off, so the download fails instead of ending as a short file. ## Compared with the REST API | Situation | MCP server | REST API | | ------------------ | --------------------------------------- | -------------------------------------------------------------------------------- | | Missing permission | `403` | `400` with code `50`, `ERROR_NOT_ENOUGH_PERMISSIONS` | | Rate limit | `429` with `Retry-After` | `429`, `ERROR_TOO_MANY_REQUESTS` (code `182`), with `Retry-After` when available | | Invalid input | `422` | `400` or `422`, depending on the error | | Error body | MCP error result with a tool error code | JSON with `success`, `http_status`, `code`, `name` and `message` | The REST API's side is in [errors](/concepts/errors/), the [error codes](/reference/errors/) and [rate limits and retries](/concepts/rate-limits-and-retries/).