feat: enhance error handling with JSON parsing and response truncation

[cherkanovart]

Description

Improves API error handling when responses are non-JSON (e.g. 502 HTML pages) or very long:

• Safe JSON parsing: Added _safe_parse_json() so that when the API returns HTML or other non-JSON (e.g. 502 gateway pages), the code raises a clear RuntimeError instead of a raw JSONDecodeError.
• Response truncation: Added _truncate_response() so error messages use a short preview (e.g. 200 chars + ...) instead of dumping the full response body.
• Consistent error messages: All error paths now include status code and a truncated response preview (e.g. Request failed (401): {"message":"Invalid credentials."}).

Used in _localize_chunk, recognize_locale, and whoami. New unit tests cover the helpers and mocked 502/HTML and truncation behavior.

Type of Change

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• Documentation update
• Performance improvement
• Code refactoring

Testing

• Tests pass locally
• New tests added for new functionality
• Integration tests pass (optional; no change to integration test behavior)

Checklist

• My code follows the style guidelines of this project
• I have performed a self-review of my own code
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation
• My changes generate no new warnings
• New and existing unit tests pass locally with my changes

Summary by CodeRabbit

• New Features

  • Added safer JSON-handling utilities to improve response parsing and error previews.

• Bug Fixes

  • Enhanced error messages to include concise response previews for HTTP failures and non-JSON responses.
  • More robust fallback behavior when parsing invalid or HTML responses.

• Tests

  • Expanded tests for error handling, truncation behavior, non-JSON/HTML responses, and CI-aware integration behavior.

[coderabbitai]

📝 Walkthrough

Walkthrough

Adds two static helpers, _truncate_response and _safe_parse_json, refactors several engine error paths to use them and include truncated response previews, imports json, and expands test coverage for error handling and CI-aware integration behavior.

Changes

Cohort / File(s)	Summary
Core Engine Improvements src/lingodotdev/engine.py	Added _truncate_response and _safe_parse_json static helpers; replaced direct JSON parsing with _safe_parse_json; updated error paths in _localize_chunk, recognize_locale, and whoami to include truncated response previews; added import json.
Error Handling Test Coverage tests/test_engine.py	Added extensive tests (TestErrorHandling, TestErrorHandlingIntegration) covering truncation, safe JSON parsing for non-JSON/HTML responses, 502/503 scenarios, and mock httpx.Response/AsyncClient.post behaviors; adjusted mocks/text in prior tests.
CI-aware Integration Tests tests/test_integration.py	Introduced IS_CI detection (env CI or GITHUB_ACTIONS) and applied pytest.xfail to TestRealAPIIntegration when running in CI; preserved existing API-key skip logic.

Sequence Diagram(s)

(omitted)

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~45 minutes

Poem

🐰 I nibble bytes and trim the blight,
I parse the dark where JSON hides at night.
I clip long errors down to a gleam,
I whisper previews, neat and clean.
Hop on — safe parsing in every byte.

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately and specifically describes the main changes in the changeset: introducing JSON parsing safety helpers and response truncation for improved error handling.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch fix/handle-502-html-errors

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}