Responses and errors

A successful request returns the status 200 and the result of the action as JSON. If the action has no result, the status is 204. If you create a record or upload a file, the status is 201, and the Location header contains the URL of the new record or file.

An error returns problem details (application/problem+json, see RFC 9457):

json

{
    "type": "about:blank",
    "title": "Forbidden",
    "status": 403,
    "detail": "Missing scope: content:write"
}

type: The URL of the exception code in the TYPO3 exception reference, for an error from an action. For example https://typo3.org/go/exception/CMS/1766253177. For an error without an exception code, for example a missing scope or an unknown endpoint, and for the status 500, the value is about:blank.
title: The reason phrase of the status code, for example Not Found.
status: The HTTP status code.
detail: The message of the error.
errors: For invalid parameters (status 400), the list of all invalid parameters. Each entry has a detail. It also has the JSON pointer into the request body, or the name of the query or path parameter.
requestId: For the status 500, the ID of the request in the log. The response contains no internal details.

The response lists all invalid parameters of a request

json

{
    "type": "https://typo3.org/go/exception/CMS/1793870606",
    "title": "Bad Request",
    "status": 400,
    "detail": "The request contains invalid parameters",
    "errors": [
        {
            "pointer": "#/record/title",
            "detail": "Integer value found, but a string is required"
        }
    ]
}

The OAuth endpoints use the error format of OAuth 2.0 (RFC 6749), for example {"error": "invalid_client", …}, because OAuth client libraries expect it.

Status	Meaning
`400`	A parameter is missing, the JSON is not valid, or a value does not agree with the JSON Schema of the action. The action can also reject a value, for example an invalid `cursor`.
`401`	The token is missing, not valid, expired or revoked. The header `WWW-Authenticate` contains `Bearer`, with `error="invalid_token"` if the request contained a token.
`403`	The app does not have a scope of the action, or the data needs a scope that the app does not have, for example `admin` for backend users. Or the backend user does not have a permission. For a missing scope, the header `WWW-Authenticate` names the scope with `error="insufficient_scope"`.
`404`	The endpoint or the requested entity does not exist, or the action is only for the backend user interface. If you change a record or create it on a page that does not exist, the status is `400`.
`409`	The request conflicts with the current state, for example a file with the same name exists.
`415`	The content type of the request body is not `application/json`.
`500`	An unexpected error occurred, for example the result of the action does not agree with its JSON Schema. TYPO3 logs the error, and the response contains its `requestId`.

Order of the checks#

A request passes these checks in this order. The first check that fails sets the response. A request with a token that is not valid thus never gets the status 400.

Only actions that declare the created resource return the status 201 and the Location header.