[Import Content]: Improve `context` Object Structure in Error Responses

Taks

This spike explores whether we can improve the readability and clarity of the context object in error responses returned by the Content Import API. The goal is to make the structure more intuitive and user-friendly—especially for non-technical users or developers unfamiliar with error formats.

Current Behavior

Example error response from the import endpoint:

{
  "error": [
    {
      "code": "INVALID_JSON",
      "context": {
        "column": 2,
        "line": 1,
        "parseError": "Unexpected end-of-input: expected close marker for Object"
      },
      "field": "keyvalue"
    }
  ]
}

Proposed Improvement

Consider renaming the context object to details and making the parseError field more user-friendly, like errorHint:

{
  "error": [
    {
      "code": "INVALID_JSON",
      "details": {
        "column": 2,
        "line": 1,
        "errorHint": "Unexpected end-of-input: expected close marker for Object"
      },
      "field": "keyvalue"
    }
  ]
}

This naming is more approachable and communicates intent better to end users and front-end consumers of the API.

Proposed Objective

User Experience

Proposed Priority

Priority 4 – Trivial

Acceptance Criteria

• [ ] Investigate whether renaming context to details is technically feasible across all relevant Import Content API responses.
• [ ] Assess the impact of renaming parseError to a friendlier key like errorHint.
• [ ] Open a discussion with the team (or product) to decide:
• Is this change valuable enough to justify?
• Is it backwards-compatible or does it require versioning?

Start by reviewing the Content Import API error response contract and every response that uses the context and parseError fields. Assess whether details and errorHint are feasible and backward-compatible, then document the team or product decision and any versioning requirement as done.