Developers
ChangelogSupportcoevera.comGet API keys
Set your API contextPick a region and space ID once. Every sample fills in your base URL.
Where do I find these?

In Coevera: open your space's API application and choose Show Access. It shows the space ID and the base URL, whose host starts with your region.

From the API: if you know the space ID, the discovery endpoint GET /api/discovery/spaces/{space_id} returns its region and base URLs, without credentials.

Only the region and space ID are kept, in this browser. Never paste a key or password here.

More in the quickstart

AI & MCPLimits and errors

Limits and errors

View as Markdown/ai/limits-and-errors.mdOpen in ClaudeAsk Claude about this pageOpen in ChatGPTAsk ChatGPT about this page

The MCP server's HTTP statuses, tool error codes, rate limits and per-call limits, and where they differ from the REST API.

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 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.

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.

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.

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, the error codes and rate limits and retries.