Errors and results
Results
Section titled “Results”Every successful tool call returns:
structuredContent: the REST envelope,{ data, meta? }. Page lists havemeta: { page, perPage, total }; cursor listsmeta: { nextCursor }; dry runsmeta.dryRun: true; a deduplicated activitymeta.deduplicated: true.- one
textcontent item with the same JSON, for clients that ignore structured content.
Tool errors
Section titled “Tool errors”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.
What to do
Section titled “What to do”| 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.
Batches
Section titled “Batches”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.
Retrying safely
Section titled “Retrying safely”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.