Skip to content

Errors and results

Every successful tool call returns:

  • structuredContent: the REST envelope, { data, meta? }. Page lists have meta: { page, perPage, total }; cursor lists meta: { nextCursor }; dry runs meta.dryRun: true; a deduplicated activity meta.deduplicated: true.
  • one text content item with the same JSON, for clients that ignore structured content.

Errors are tool results with isError: true and the REST error object, so the model can read them and correct the call:

{
"isError": true,
"structuredContent": {
"error": {
"code": "STAGE_NOT_FOUND",
"message": "No stage called \"Propuesta\" in this pipeline.",
"details": { "allowed": ["Lead", "Qualified", "Proposal", "Negotiation", "Won", "Lost"] }
}
}
}

details names the field and, where useful, the allowed values. Unexpected failures are INTERNAL_ERROR.

Code Do
VALIDATION_FAILED Fix details.fields[].field (reason and message per field)
FILTER_INVALID Use a field or op from details.allowed
STAGE_NOT_FOUND, STAGE_NOT_IN_PIPELINE Pick from details.allowed
MATCH_KEY_MISSING The upsert item lacks the matchOn key; FREE_MAIL_DOMAIN: skip that organization
DUPLICATE Use details.existingId, or upsert instead of create
VERSION_CONFLICT Re-read (details.current), re-apply your change, retry
IDEMPOTENCY_IN_PROGRESS Wait a second, retry with the same key
IDEMPOTENCY_KEY_REUSED A new request needs a new key
RELATED_RECORD_NOT_FOUND A linked id is not in this account
NOT_FOUND Wrong id, or another account’s
FORBIDDEN The key lacks details.required. Do not retry; tell a person
PLAN_LIMIT_REACHED Do not retry or work around it. Finish what you can and tell a person the message as is
ACCOUNT_REQUIRED, ACCOUNT_NOT_FOUND Multi-account connection: pass an accountId from details.accounts
RATE_LIMITED Comes as HTTP 429 before any tool runs. Wait Retry-After seconds, then retry

The full list with HTTP statuses is in error codes.

upsert_records and log_activity with items never fail as a whole for one bad item: the result is a list of { index, result, id?, error? }. Check every error, fix those items and send only them again.

Send an idempotencyKey on every write you might repeat. If a call times out, repeat it with the same key: you get the first result instead of a second write. Client errors are stored under the key too, so after you change the arguments, use a new key.