nds newsletter  ](../../newsletter/)
  * [ About  ](../../about/)

About

    * [ Alternatives, Inspiration and Comparisons  ](../../alternatives/)
    * [ History, Design and Future  ](../../history-design-future/)
    * [ Benchmarks  ](../../benchmarks/)
  * [ Help  ](../../help/)

Help

    * [ Help FastAPI - Get Help  ](../../help-fastapi/)
    * [ Development - Contributing  ](../../contributing/)
  * [ Release Notes  ](../../release-notes/)

Table of contents

  * Additional Response with ` model `
  * Additional media types for the main response 
  * Combining information 
  * Combine predefined responses and custom ones 
  * More information about OpenAPI responses 

  1. [ FastAPI  ](../..)
  2. [ Learn  ](../../learn/)
  3. [ Advanced User Guide  ](../)

#  Additional Responses in OpenAPI  ¶

Warning

This is a rather advanced topic.

If you are starting with **FastAPI** , you might not need this.

You can declare additional responses, with additional status codes, media
types, descriptions, etc.

Those additional responses will be included in the OpenAPI schema, so they
will also appear in the API docs.

But for those additional responses you have to make sure you return a `
Response ` like ` JSONResponse ` directly, with your status code and content.

##  Additional Response with ` model ` ¶

You can pass to your _path operation decorators_ a parameter ` responses ` .

It receives a ` dict ` , the keys are status codes for each response, like `
200 ` , and the values are other ` dict ` s with the information for each of
them.

Each of those response ` dict ` s can have a key ` model ` , containing a
Pydantic model, just like ` response_model ` .

**FastAPI** will take that model, generate its JSON Schema and include it in
the correct place in OpenAPI.

For example, to declare another response with a status code ` 404 ` and a
Pydantic model ` Message ` , you can write:

    
    
    from fastapi import FastAPI
    from fastapi.responses import JSONResponse
    from pydantic import BaseModel
    
    
    class Item(BaseModel):
        id: str
        value: str
    
    
    class Message(BaseModel):
        message: str
    
    
    app = FastAPI()
    
    
    @app.get("/items/{item_id}", response_model=Item, responses={404: {"model": Message}})
    async def read_item(item_id: str):
        if item_id == "foo":
            return {"id": "foo", "value": "there goes my hero"}
        return JSONResponse(status_code=404, content={"message": "Item not found"})
    

Note

Keep in mind that you have to return the ` JSONResponse ` directly.

Info

The ` model ` key is not part of OpenAPI.

**FastAPI** will take the Pydantic model from there, generate the ` JSON
Schema ` , and put it in the correct place.

The correct place is:

  * In the key ` content ` , that has as value another JSON object ( ` dict ` ) that contains: 
    * A key with the media type, e.g. ` application/json ` , that contains as value another JSON object, that contains: 
      * A key ` schema ` , that has as the value the JSON Schema from the model, here's the correct place. 
        * **FastAPI** adds a reference here to the global JSON Schemas in another place in your OpenAPI instead of including it directly. This way, other applications and clients can use those JSON Schemas directly, provide better code generation tools, etc. 

The generated responses in the OpenAPI for this _path operation_ will be:

    
    
    {
        "responses": {
            "404": {
                "description": "Additional Response",
                "content": {
                    "application/json": {
                        "schema": {
                            "$ref": "#/components/schemas/Message"
                        }
                    }
                }
            },
            "200": {
                "description": "Successful Response",
                "content": {
                    "application/json": {
                        "schema": {