Error Handling

Every FieldMCP tool returns either a success response or a structured error in the MCP content array with isError: true. Errors include machine-readable codes, human-readable messages, and recovery hints so AI assistants can reason about what went wrong.

Rate limit errors are returned as HTTP 429 with the X-RateLimit-Remaining header, not as tool-level error codes. See Rate Limits for that path.

Error Response Shape

When a tool call fails, the response includes a JSON object with these fields:

{
  "error": true,
  "code": "FIELD_NOT_FOUND",
  "message": "field 'xyz' not found",
  "retryable": false,
  "suggestedAction": "Use deere_list_resources with resourceType='fields' to find valid field IDs.",
  "requestId": "req-abc123"
}

All Fields

Field	Type	Always present	Description
`error`	`true`	Yes	Distinguishes errors from success responses
`code`	string	Yes	Machine-readable error code (see tables below)
`message`	string	Yes	Human-readable description
`retryable`	boolean	Yes	Whether retrying the same request may succeed
`suggestedAction`	string	Usually	Recovery hint for the AI assistant or developer
`requestId`	string	Sometimes	For support escalation
`param`	string	Validation errors	Which parameter failed
`providedValue`	any	Validation errors	What was provided
`expectedType`	string	Validation errors	What was expected
`retryAfter`	number	Rate limit errors	Seconds until retry is allowed
`provider`	string	Auth/provider errors	Which provider (e.g., "John Deere")
`missingScopes`	string[]	Missing scope errors	Which OAuth scopes are needed
`resourceId`	string	Resource errors	ID of the resource not found
`resourceType`	string	Resource errors	Type: `field`, `organization`, `equipment`, `farm`, `operation`, `boundary`
`succeeded`	array	Partial success	Items that completed successfully
`failed`	array	Partial success	Items that failed with their error codes
`missingData`	array	Data quality errors	What data is missing and its impact

Error Codes

Validation Errors

These fire when the tool call has invalid input. Not retryable. Fix the input and try again.

Code	When it fires	Recovery
`MISSING_REQUIRED_PARAM`	A required parameter was not provided	Check the tool's parameter table. Provide the missing parameter.
`INVALID_PARAM_VALUE`	A parameter has a value outside the allowed range or set	Check the allowed values. The `providedValue` and `expectedType` fields tell you exactly what was wrong.
`INVALID_PARAM_TYPE`	A parameter has the wrong type (e.g., string instead of number)	Fix the type. The `expectedType` field shows what's needed.
`MUTUALLY_EXCLUSIVE_PARAMS`	Two parameters that can't be used together were both provided	Remove one of the conflicting parameters. The `message` names both.

Authentication Errors

These fire when the farmer's connection to a provider is broken. Not retryable by the AI assistant. The farmer needs to take action in the Dashboard.

Code	When it fires	Recovery
`TOKEN_EXPIRED`	The farmer's John Deere access token has expired and could not be refreshed	This is the farmer's Deere token, not your JWT. The farmer needs to re-authorize John Deere access in the dashboard.
`TOKEN_REVOKED`	The farmer revoked access in their John Deere account	The farmer needs to re-connect their John Deere account in the dashboard.
`MISSING_SCOPE`	The farmer's connection lacks required OAuth scopes	The farmer needs to re-authorize with the required scopes (listed in `missingScopes`).
`PROVIDER_NOT_CONNECTED`	The farmer hasn't connected the requested provider	The farmer needs to connect their account in the dashboard before using tools for that provider.

Rate Limiting

Code	When it fires	Recovery
`RATE_LIMIT_ORG`	Tool-level escape hatch for per-org rate limiting. Currently not emitted in production. Actual rate limits surface as HTTP 429.	See Rate Limits. Wait `retryAfter` seconds.
`RATE_LIMIT_PROVIDER`	John Deere's own API rate limit was hit. The gateway retries automatically before surfacing this.	Wait `retryAfter` seconds. The provider is temporarily throttling requests.

Resource Errors

These fire when the requested data doesn't exist. Not retryable with the same input.

Code	When it fires	Recovery
`RESOURCE_NOT_FOUND`	A generic resource lookup failed	Use `deere_list_resources` to discover available resources.
`FIELD_NOT_FOUND`	The specified field doesn't exist in the organization	Use `deere_list_resources` with `resourceType='fields'` to find valid field IDs.
`ORG_NOT_FOUND`	The specified organization doesn't exist	Use `deere_list_resources` with `resourceType='organizations'` to find valid org IDs.
`EQUIPMENT_NOT_FOUND`	The specified equipment doesn't exist	Use `deere_list_resources` with `resourceType='equipment'` to find valid equipment IDs.
`BOUNDARY_NOT_FOUND`	The requested boundary doesn't exist for the field	Use `deere_list_resources` with `resourceType='boundaries'` and the field's `orgId` to find valid boundary IDs for that field.

Provider Errors

These fire when the upstream provider (John Deere) has issues. May be retryable.

Code	Retryable	When it fires	Recovery
`PROVIDER_UNAVAILABLE`	Yes	John Deere API is down or unreachable	Wait `retryAfter` seconds (default 30s). Provider may be experiencing an outage.
`PROVIDER_TIMEOUT`	Yes	John Deere API request timed out	Retry. Consider requesting less data (shorter date range, fewer include options).
`PROVIDER_ERROR`	5xx: Yes, 4xx: No	John Deere returned an unexpected error	For 5xx: retry shortly. For 4xx: check the request parameters.

Data Quality Errors

These fire when the field exists but lacks sufficient data for the requested analysis.

Code	When it fires	Recovery
`INSUFFICIENT_DATA`	Critical data is missing for the analysis	Check the `missingData` array. Each entry lists what's missing, its impact (`required` / `degraded` / `optional`), and a message explaining what to do.
`NO_DATA_FOR_PERIOD`	No data exists for the requested time period	Try a different time period. Use `deere_search_operations` to discover what data is available.

Partial Failures

Code	When it fires	Recovery
`PARTIAL_SUCCESS`	Some items in a batch succeeded, others failed	Read the `succeeded` array for completed items. Read the `failed` array for items that need attention. Each failed item has its own `code` and `message`. If any failures are retryable (`PROVIDER_TIMEOUT`, `PROVIDER_UNAVAILABLE`, `RATE_LIMIT_PROVIDER`), retry those items.

Internal Errors

Code	When it fires	Recovery
`INTERNAL_ERROR`	An unexpected error occurred in the gateway	Include the `requestId` when contacting support. This should not happen in normal operation.

Recovery Decision Tree

Is the error retryable?
├── Yes → Wait `retryAfter` seconds, then retry
│   ├── Still failing after 3 retries → Stop, surface the error
│   └── Succeeds → Continue
└── No → Check the error category:
    ├── Validation → Fix the input parameters
    ├── Auth → Farmer needs to re-authorize in the dashboard
    ├── Resource → Use deere_list_resources to find valid IDs
    ├── Data Quality → Try different time period or provide more input data
    ├── Partial → Process succeeded items, retry or report failed items
    └── Internal → Contact support with requestId

Retry Strategy

For retryable errors, use exponential backoff with jitter:

attempt 1: wait retryAfter seconds (from the error response)
attempt 2: wait retryAfter × 2 + random(0-1000ms)
attempt 3: wait retryAfter × 4 + random(0-1000ms)
give up after 3 attempts

If the error includes a retryAfter field, always respect it. If not, start with 2 seconds.

Common Recovery Patterns

"TOKEN_EXPIRED" keeps firing

This means the farmer's John Deere session has expired and the gateway couldn't auto-refresh it. The farmer needs to visit the Dashboard and click "Reconnect" for John Deere. The access token typically lasts ~90 days. If this fires repeatedly, check whether the farmer revoked access in their John Deere account.

"PROVIDER_UNAVAILABLE" on all requests

John Deere's API may be experiencing an outage. Check John Deere's status page or wait 5-10 minutes. The gateway automatically retries with backoff before surfacing this error.

"PARTIAL_SUCCESS" on batch operations

Some items succeeded, some failed. The succeeded and failed arrays give you the full picture. Process the successful results immediately. For failed items, check if their individual error codes are retryable. If yes, retry just those items. If no, report the failures to the user with the specific error messages.

See Rate Limits for HTTP 429 recovery. See individual tool pages for the specific errors each tool can emit.