{
  "id": 16525749,
  "title": "Clear JSON Errors in FastAPI: One Shape for Every Failure",
  "url": "https://urgent.news/2026/10/25/clear-json-errors-in-fastapi-one-shape-for-every-failure",
  "topic": "tech",
  "section": "Tech",
  "published": "2026-10-25T21:52:50.000Z",
  "source": {
    "name": "Dev.to",
    "slug": "dev-to",
    "url": "https://dev.to/team_bytebridgetalentllc/clear-json-errors-in-fastapi-one-shape-for-every-failure-1bnc"
  },
  "original_language": "en",
  "account": "FastAPI, a popular Python web framework, can return errors with different JSON structures depending on the type of exception that occurs. When a developer does not provide custom exception handlers, FastAPI generates two distinct JSON error shapes for the same HTTP status code.\n\nIn the first error, the \"detail\" field contains a string, such as \"Book not found\". In the second error, the \"detail\" field holds a list of objects that describe the specific issue encountered. This discrepancy in error shapes can cause client code to struggle with handling errors consistently.\n\nTo address this issue, the author of the post introduces a single, uniform JSON error shape for all exceptions. This approach simplifies error handling for client code, as they would only need to check for a single \"error\" field with consistent keys. The chosen JSON shape consists of three main fields: \"error\", \"status\", \"code\", and \"message\". The \"status\" field mirrors the HTTP status code, aiding in log analysis. The \"code\" field is an easily recognizable, stable string that remains constant across different errors. The \"message\" field is intended for human-readable error descriptions.\n\nBy implementing this consistent error shape, developers can avoid the need to handle multiple JSON structures for the same error code. This simplification enhances the maintainability and readability of API client code. Additionally, the post mentions that the Problem Details format (RFC 9457) is another viable option for providing a standardized JSON error structure for public APIs.",
  "summary": "Updated: October 26, 2026 A phone app calls an API and gets an error. The app wants to show a short, kind message. But the error comes back in a shape the app did not expect, so it shows \"undefined\" instead. This happens a lot. FastAPI is easy to work with. Its default errors just do not all look alike. Below, every error gets one JSON shape, and a few tests check it. Tested with: Python 3.13.5,…",
  "key_points": [
    "FastAPI generates two distinct JSON error shapes for the same HTTP status code.",
    "Author introduces a single, uniform JSON error shape for all exceptions.",
    "Consistent error shape simplifies client code handling and enhances API maintainability."
  ],
  "editors_take": null,
  "illustration": null,
  "coverage": {
    "outlets": 1,
    "also_reported_by": []
  },
  "ai_generated": true,
  "disclaimer": "Summaries, key points and the editor’s take are written by software from other outlets’ reporting and may contain errors — always check the linked original."
}