Troubleshooting
Connections
| Problem | Likely cause | Fix |
|---|---|---|
| Request API access shows instead of connection options | API access isn't enabled for the organization. | Request it and wait for FieldTask to enable it. |
Every request returns 403 api_access_not_enabled | Access was disabled for the organization. | Contact FieldTask. |
401 invalid_token | The token expired, was rotated or revoked, has a typo, or isn't a REST credential (for example, an MCP sign-in). | Check the token's status in Settings → API connections. Create or rotate a token if needed. |
OAuth token request returns invalid_target | resource is missing, repeated or doesn't match the REST resource. | Send resource once, exactly as shown with the connection. |
| A lost OAuth client secret | Secrets are shown only once. | Rotate the secret instead of creating another connection. |
Permissions and features
| Problem | Likely cause | Fix |
|---|---|---|
403 with error.code: missing_permission | The connection lacks a permission, possibly one needed by an optional input such as location_id. | Add the permission named in error.message. See Permissions. |
| A field is missing from responses | The field needs a related read permission, such as customers:read for a job's customer. | Add the read permission. |
405 method_not_allowed on a create | That create isn't enabled in this environment. | Contact FieldTask. |
422 validation_failed on a timed job, assignees or items | That feature isn't enabled, or an input is invalid. | Check the input against the field guide; if it's valid, contact FieldTask. |
Creates and retries
| Problem | Likely cause | Fix |
|---|---|---|
| A record was created twice | The retry used a new idempotency key, or no key. | Always save a key before sending and reuse it for retries. See Idempotency. |
409 idempotency_key_reused | The retry's body differs from the original, even slightly (for example a field added as null). | Resend the exact original body. |
409 external_reference_conflict | Another record already uses that reference. | Look it up with ?external_reference=… instead of creating it again. |
422 validation_failed with a valid-looking body | A referenced record is inactive, belongs to another customer or organization, or isn't eligible. | Re-read the referenced records with the list endpoints. |
MCP clients
| Problem | Likely cause | Fix |
|---|---|---|
| FieldTask tools don't appear | The connection wasn't approved, was revoked, or the client hasn't refreshed its tools. | Check Active connections, reconnect if needed, and refresh the client's tools. |
| A tool you expect is missing | The connection lacks its permission, or the feature isn't enabled. | Add the permission; the person who connected the client must approve it. |
| New permissions don't take effect | Added permissions wait for approval. | The person who connected the client reconnects and approves, then refreshes tools. |
| The client asks for an ID | It couldn't resolve a name. | Give more detail, such as the customer's email or address. |
Getting help
When you contact support, include the time, the method and path (or tool name), the status and code, and the X-Request-ID (request_id for MCP). Never include tokens, client secrets or invitation links.