Skip to content
Browse docsErrors and limits

Errors and limits

What each kind of failure looks like, and how to retry safely.

Connection errors#

ResponseMeaningWhat to do
HTTP 401 with WWW-AuthenticateNo token, or the token expired or was revokedLet your client refresh, or sign in again.
HTTP 401 for a member who left GravityAccess ended with their membershipNothing. The account can't be used.
HTTP 403 with error="insufficient_scope"The token lacks the read or edit permission for this operationContinue within the granted permissions, or authorize the scopes in the challenge if you want the additional capability.
HTTP 429 with error="rate_limit_exceeded"A message other than a single tool call went over the member's read or write limitRespect Retry-After before retrying. Nothing in the request ran.
HTTP 503 with "MCP authorization is temporarily unavailable."Gravity's sign-in service is downTry again later.

Tool errors#

Input validation failures use invalid_argument for goal, group, and person reads, or request_rejected for other tools in the error envelope below; no application operation runs. The message identifies the details to correct, and recovery distinguishes a corrected request from a required current read or identity lookup. The registered input schemas remain strict. Unknown tools and malformed protocol messages produce protocol errors.

Executed-tool errors return { status: "error", code, message, recovery } as both structuredContent and JSON text, with isError: true. Goal save and search conflicts can include currentState. An ending conflict can identify the changed goal; read its current state before retrying. Known goal/run IDs may also be included. Messages explain the situation; codes and recovery values are stable.

The message is member-facing guidance, never a raw exception. Agents should explain it plainly and use recovery, IDs, and versions to choose their next tool call without repeating those technical fields to the member. Do not expose database errors, queries, stack traces, provider diagnostics, or private payloads, and do not guess the technical cause. Unexpected failures retain diagnostics separately; tool results contain only the safe explanation and recovery. Goal search projections expose status and progress, not stored free-text error messages.

CodeRecoveryMeaning and next step
invalid_argumentcorrect_inputGoal, group, or person read input or continuation is invalid. Restart a list without its token when the token expired or belongs to another request.
already_existsread_before_retryThe person or address already exists. Review currentPerson before deciding whether another change is needed.
unavailableresolve_idAn exact group or goal is missing or inaccessible. Resolve from current authorized lists; do not guess IDs.
version_conflictread_before_retryThe goal changed since it was read. The edit or ending was rejected unchanged; a rejected ending batch ends none. Read current state before preparing a revised action.
clarification_requiredclarify_goalThe goal needs clarification before a search can start. Read its question and help answer it; no search started.
request_rejectednew_request, read_before_retry, or resolve_idInvalid input or an application rule rejected the request before changes. Correct the details, read current state, or resolve the person, goal, or group as directed by recovery.
operation_failedretry_read for reads; read_before_retry for writesAn unexpected failure left the outcome unconfirmed. Reads can be retried. Read current state before considering another write.
invalid_responseretry_read for reads; read_before_retry for writesThe application's response did not meet the tool contract. No malformed/private payload is returned. The outcome is unconfirmed; use the same recovery as an unexpected failure.
rate_limitedretry_laterThe member went over the read or write limit before this tool ran. Nothing changed and no search started. Wait retryAfterSeconds, then repeat the same call.

An accessible empty list is successful. Missing and inaccessible exact resources both return unavailable, without disclosing which condition applies.

Example conflict:

json
{
  "status": "error",
  "code": "version_conflict",
  "message": "The goal has changed since this edit was prepared. Review its current state.",
  "recovery": "read_before_retry"
}

Repeating a call#

Writes compare the request with current state:

  • A goal edit whose supplied fields already match current state returns no_change with current state and performs no write or search, even when a supplied version is old. Person Update requires a current etag even for a no-op and returns the canonical Person on success.
  • create_goal refuses wording that matches an active goal, create_group refuses a name of a group you already moderate, and each returns request_rejected with the existing goal or group. create_person refuses an owned email or a matching name without emails using already_exists and currentPerson.
  • end_goal and batch_end_goals return no_change for already-ended owned goals, at any supplied version. The saved reason, retirement time, and version remain unchanged.
  • start_goal_search returns the search already running instead of starting another. Once it finishes, another explicit full search is allowed. Each MCP call gets a new request identity; read search status after an uncertain response before retrying. There is no caller-key replay guarantee.

create_goal also gets a fresh request identity on each MCP call and exposes no caller retry key. After an uncertain response, read list_goals and the relevant get_goal before considering another create. Its duplicate check covers active self-goals with the same wording; it cannot replay an earlier creation after that goal changes or ends.

A supplied stale version rejects an edit that would change state. Otherwise the patch applies atomically.

Goal edits and ending require expectedVersion, copied unchanged from the opaque version in an owned goal read. Content, audience visibility, beneficiary reconciliation, and lifecycle changes invalidate that token. Search progress and display names do not. Omitting a field preserves its current value, including when other actors edit concurrently.

Search requests capture current matching inputs atomically. Optional expectedScopeVersion requires the goal to still have the scope you read; superseded inputs conflict.

Goal wording, private details, audience, and visibility commit together. Rejected edits change nothing. MCP saving starts no search, so search failure cannot turn a save into a partial save/search outcome.

Limits#

LimitValue
Goal text2,000 characters
Private details (additionalContext)4,000 characters
Groups per goal100
Exact goals per atomic batch_end_goals call100
Goals per list_goals page20 by default, maximum 100
Invitations per list_invitations page20 by default, maximum 100
Running searches per goal1
People per issue_invitations call10
Invitation links per member20 per day
Invitation note500 characters
Group name and description100 and 500 characters
MCP reads per member100 per minute, shared across clients
MCP writes per member30 per minute, shared across clients
Access token lifetime1 hour
Staying connected (offline_access)Until 90 days without use

Sign-in endpoints are rate limited. If you see HTTP 429 while signing in, wait a minute and try again.

MCP discovery and transport messages count toward the read limit. A single tool call over the limit returns the rate_limited tool error, so the agent can wait and retry. Other messages over the limit, and any batch, receive HTTP 429. Each message in a JSON-RPC batch counts separately, and a batch above either limit is rejected before any tool runs. The application-level batch_end_goals is one bounded tool call and counts as one write. Both responses include Retry-After: 60.

Each search does real work for every network it covers. Start one only when you're asked, and never in a loop. A full search on a goal that was already searched replaces matches nobody has acted on.

Contact identity and private notes#

get_person, create_person, update_person and add_person_email share the canonical Person resource and quoted opaque etag. Update requires an exact current etag, even for no-ops. Stale values return version_conflict with currentPerson; review before retrying. Create needs person.ownerAuthoredName and rejects collisions with already_exists. It never upserts.

Update uses an optional comma-separated updateMask: omission infers populated nonempty values; an empty mask changes nothing; explicit selected absent/null scalar fields reset. * replaces all writable fields and can affect newly introduced fields. Emails are output-only on Update; add_person_email adds one normalized address, returning already_exists for duplicates and rejecting another person's address. No email removal or merge is supported.

Create accepts up to 20 initial addresses. An email address can be up to 254 characters. A private label can be up to 120 characters, a LinkedIn URL 2,048, and LinkedIn company and position 200 each.

Use add_notes for profile corrections. One request accepts 1–24 notes, each with up to 4,000 characters of text, 500 per qualifier, and 1,000 for the reason. Reuse the request UUID only when retrying the identical batch.