ERR_PIPEDRIVE_DEAL_FIELD on Pipedrive: Pipedrive deal field update failed. Root cause: Pipedrive deal field update failures are almost always caused by sending an incorrect field key or an invalid option value for a custom field. Pipedrive custom fields use machine-generated hash keys (e.g., "a1b2c3d4e5f6") rather than human-readable names. Integrations that were built using field names instead of field keys, or that reference field keys from a different Pipedrive account, will consistently fail. Additionally, custom fields of type "Enum" (dropdown) or "Set" (multi-select) require the numeric option ID, not the option label string. Step 1: Retrieve the correct field key from the Pipedrive API. Pipedrive custom field keys are account-specific hashes that look like "a1b2c3d4e5f6789012345678". To get the correct key for each field, call GET https://api.pipedrive.com/v1/dealFields?api_token=YOUR_TOKEN. The response lists all deal fields with their "key" property — use this key (not the field name) in your API update calls. Standard fields use simple keys like "title", "value", "status", "pipeline_id", "stage_id", "person_id", "org_id". Custom fields always use the hash key. Step 2: Get the correct option IDs for Enum and Set fields. For custom fields of type "Enum" (single dropdown) or "Set" (multi-select), you cannot send the option label string — you must send the numeric option ID. In the dealFields API response, each Enum/Set field has an "options" array: [{"id": 123, "label": "Qualified"}, {"id": 124, "label": "Unqualified"}]. Use the "id" value (123 or 124), not the "label" string. If you send "Qualified" instead of 123, Pipedrive returns a 400 error. Build a lookup table in your integration that maps option labels to IDs at setup time. Step 3: Validate stage_id and pipeline_id combinations. When updating a deal's stage, you must send a stage_id that belongs to the pipeline_id you are targeting. Sending a stage_id from a different pipeline causes a validation error. Call GET /v1/stages?pipeline_id=YOUR_PIPELINE_ID to get the valid stage IDs for a specific pipeline. If you are moving a deal to a different pipeline, update both pipeline_id and stage_id in the same API call — updating only one without the other causes a mismatch error. Step 4: Check field visibility and permissions. Pipedrive has field-level visibility settings that can prevent API updates even with a valid API token. In Pipedrive, go to Company Settings → Data Fields → Deal Fields and check whether the field you are trying to update has any visibility restrictions. Additionally, if you are using an API token from a user account (not an admin account), the user must have permission to edit the specific deal and the specific field. Use an admin account's API token for integration purposes to avoid permission-related failures. Step 5: Handle the 429 rate limit for bulk updates. Pipedrive enforces a rate limit of 100 API requests per 2 seconds per API token. For bulk deal updates (e.g., updating 500 deals from a CSV import), you will hit this limit quickly. Implement exponential backoff: when you receive a 429 response, check the "Retry-After" header for the number of seconds to wait, then retry the request. For large bulk operations, spread requests over time using a queue with a rate limiter set to 45 requests per second (below the 50/second limit) to avoid 429 errors entirely. Step 6: Use the batch update endpoint for efficiency. Pipedrive's v1 API does not have a native batch update endpoint for deals, but you can reduce API calls by using the PATCH /v1/deals/{id} endpoint with multiple fields in a single request body rather than making separate calls for each field. For very large updates (1,000+ deals), consider using Pipedrive's Import feature (Company Settings → Import Data) with a CSV file, which bypasses the API rate limit entirely and is processed asynchronously by Pipedrive's backend.