Error Enrichment

Opt-in helpers to resolve fieldId values to schema display names and API names, then format write errors for logs or end-user messages. These utilities are not called automatically by insert_data, process_errors, or format_row_error_message.

💡

For HTTP exceptions, row "Errors" channels, and ErrorHandling, see Error Handling. That page covers standard SDK behavior; this page covers optional enrichment you invoke after a write.

When to use

After a write that returns row-level errors—for example RowsWriteResult.row_errors or BatchResult.row_errors—call enrichment explicitly when you want:

Developer logs / task messages with schema context (fieldName, apiName, fieldId)
Plain English messages for UI or email (no raw ids)

from dealcloud_sdk import (
    DealCloud,
    enrich_row_errors,
    format_error_with_metadata,
    format_error_message_english,
)

Building field lookup

Use cached schema fields (no extra HTTP calls per error):

lookup = dc.get_field_lookup("Company")
# {2060083: {"name": "Revenue", "apiName": "Revenue"}, ...}

If you already have get_field_map() output:

from dealcloud_sdk import build_field_lookup
 
field_map = dc.get_field_map(["Company"])
lookup = build_field_lookup(field_map, "Company")

Supported input shapes

Pass the error dict DealCloud returned. The helpers accept:

Cells API — nested error on the cell item:

{
    "entryId": -1,
    "fieldId": 2060083,
    "error": {
        "field": "0",
        "code": 5010,
        "description": "Can't change value in calculated or smart field.",
    },
}

Rows API — Errors array on the row:

{
    "EntryId": 1001,
    "Errors": [
        {
            "fieldId": 10,
            "field": "0",
            "code": 400,
            "description": "Invalid value",
        }
    ],
}

Mode A — metadata injection

Keep the API description verbatim; append bracketed schema context. Suitable for logs and operator task messages.

for err_row in write_result.row_errors:
    for item in enrich_row_errors(err_row, lookup, object_name="Company"):
        log.info(format_error_with_metadata(item))

Example output:

EntryId -1: Can't change value in calculated or smart field. [Company, fieldName Revenue, apiName Revenue, fieldId 2060083]

Row-level wrapper:

from dealcloud_sdk import format_row_error_with_metadata
 
message = format_row_error_with_metadata(
    err_row, field_lookup=lookup, object_name="Company"
)

Mode B — plain English

Fixed English templates only (no i18n). Omits fieldId, apiName, and EntryId from the string.

for err_row in write_result.row_errors:
    for item in enrich_row_errors(err_row, lookup, object_name="Company"):
        ui.show(format_error_message_english(item))

Example output:

The Revenue field on Company could not be updated: Can't change value in calculated or smart field.

End-to-end example

lookup = dc.get_field_lookup("Company")
result = dc.insert_data(
    "Company",
    records,
    output="write_result",
)
 
for err_row in result.row_errors:
    for item in enrich_row_errors(err_row, lookup, object_name="Company"):
        log.info(format_error_with_metadata(item))
        notify_user(format_error_message_english(item))

API reference

Symbol	Role
`get_field_lookup(object_id)`	On `DealCloud`; build lookup from cached fields
`build_field_lookup(field_map, object_name, schema=None)`	Build lookup from `get_field_map()` output
`field_lookup_from_fields(fields)`	Build lookup from `Field` list
`iter_row_error_items(error_row)`	Normalize Cells / Rows error dicts
`enrich_row_errors(error_row, field_lookup, object_name=None)`	Structured dicts with `fieldName`, `apiName`, etc.
`format_error_with_metadata(enriched_item)`	Mode A — metadata brackets
`format_error_message_english(enriched_item)`	Mode B — plain English
`format_row_error_with_metadata(...)`	Row wrapper for Mode A
`format_row_error_message_english(...)`	Row wrapper for Mode B