Statuses and errors

This article describes the standard HTTP status and error codes the GraphQL API returns when resolving a query.

HTTP response status codes

The GraphQL API uses standard HTTP status codes to indicate whether a request is successful or not. In general, status codes within the 2xx range indicate a successful request. When you receive an HTTP status code different from 2xx, then you probably have one of the following issues:

• Client-side validation problems like an invalid query argument or access token (4xx HTTP codes).
• Server or connection problems (5xx HTTP codes).

Example GraphQL errors

The GraphQL API also verifies if a request is syntactically correct and mistake-free in the context of a given GraphQL schema. When a query contains a mistake, an error message can be returned in the response.

See some known GraphQL errors below.

Example 1. When a query size exceeds the 8kb limit, you’ll see the following error message:

{
    "errors": [
        {
            "message": "Syntax Error: Unexpected <EOF>",
            "extensions": {
                "category": "graphql"
            },
            "locations": [
                {
                    "line": 1,
                    "column": 1
                }
            ]
        }
    ]
}

Prepr limits a query size to a maximum of 8 kb to increase data retrieval performance from the cache. The limit cannot be adjusted at the moment. We recommend that you use fragments for large requests. Alternatively, some libraries will automatically remove unnecessary whitespace and comments, like GraphQl Query Compress (opens in a new tab).

Example 2. When a wrong typecast is specified in a query (Int/String/etc.), the GraphQL API returns the following error message:

{
    "errors": [
        {
            "message": "Variable \"$id\" of type \"Int\" used in position expecting type \"String\".",
            "extensions": {
                "category": "graphql"
            },
            "locations": [
                {
                    "line": 1,
                    "column": 21
                }
            ]
        }
    ]
}

Follow the tips in the error message to resolve an issue.

Example 3. When a request contains a field that is not available in the schema definition, the following error message will be returned:

{
    "errors": [
        {
            "message": "Cannot query field \"content_ref\" on type \"Blog\".",
            "extensions": {
                "category": "graphql"
            },
            "locations": [
                {
                    "line": 5,
                    "column": 3
                }
            ]
        }
    ]
}

Check out your schema definition and update the requested field name to the correct one.

Example 4. When a typo is made in a property name, you’ll get the following error message:

{
    "errors": [
        {
            "message": "Cannot query field \"id\" on type \"Blog\". Did you mean \"_id\"?",
            "extensions": {
                "category": "graphql"
            },
            "locations": [
                {
                    "line": 3,
                    "column": 8
                }
            ]
        }
    ]
}

Follow the tips in the error message to resolve an issue.