Errors in GraphQL

Contentstack returns comprehensive error responses when a GraphQL API request fails to execute.

The “code” key in the error message provides a unique identity that highlights the main reason for partial or complete failure of the API request.The error responses also contain an additional key named “details”, which provides specific hints related to the entity causing the error. These hints also include requests to debug the GraphQL schema and check for possible discrepancies.

Let us look at the different keys that are returned within the error description:

code: Distinct identifier that highlights the main reason for partial or complete failure
message: Human-readable text message that describes the error
details: Specific hints to help debug the error

The following syntax represents an API error response:

{
    "errors": [
        {
            "message": "Failed to run query.",
            "extensions": {
                "errors": [
                    {
                        "code": "error_code",
                        "message": "Message.",
                        "details": {
                            "hint": "Hint to resolve the issue."
                        }
                    }
                ]               
            }
        }
    ]
}

Let’s look at some of the common errors that Contentstack returns when there is an issue with the GraphQL request:

HTTP Status Code	Error Message
400	Message { "code": "INVALID_REQUEST", "message": "Invalid query or request body", "details": { "hint": "The request should have a valid query or body parameters." } } Description The following scenarios return the “Invalid query or request body” error message: GET API request provides an invalid query POST API request provides an invalid JSON formatted request body
401	Message { "code": "AUTHENTICATION_FAILURE", "message": "Invalid api_key, access_token, or environment", "details": { "hint": "The URL pattern should be '/stacks/{stack_api_key}?environment={env_name}'. Pass 'access_token' via the headers." } } Description Either one or a combination of the following input parameters entered is invalid: Stack API key (authentication) Delivery token provided as the value of the access_token key (header) Publishing environment (the environment query parameter)
401	Message { "error_message": "You're not allowed in here unless you're logged in!", "error_code": 105, "errors": { "access_token": ["is not valid."] } } Description You need to log in to get access.
403	Message <html> <head> <title>403 Forbidden</title> </head> <body bgcolor="white"> <center> <h1>403 Forbidden</h1> </center> </body> </html> Description The URL path is invalid.
405	Message <html> <head> <title>405 Method Not Allowed</title> </head> <body bgcolor="white"> <center> <h1>405 Method Not Allowed</h1> </center> </body> </html> Description The method used is invalid. Make requests using only GET, POST, HEAD, or OPTIONS methods.
412	Message { "code": "MISSING_API_KEY", "message": "api_key is required", "details": { "hint": "Pass the stack api_key in the request as follows: /stacks/{stack_api_key}?environment={env_name}’." } } Description The stack api_key is missing in the request URL.
412	Message { "code": "MISSING_DELIVERY_TOKEN", "message": "access_token is required", "details": { "hint": "Pass the delivery token in the headers as: 'access_token: {delivery_token}'." } } Description The Delivery token is missing. Include it in the headers of your request as: access_token:{delivery_token}.
412	Message { "code": "MISSING_ENVIRONMENT", "message": "The "environment" query parameter is required", "details": { "hint": "The URL pattern should be '/stacks/{stack_api_key}?environment={env_name}'." } } Description The environment query parameter is missing.
412	Message { "error_message": "We can't retrieve the stack. Please recheck the entered api_key.", "error_code": 109, "hint": {Invalid "api_key"} } Description The stack api_key you entered is invalid.
414	Message <html> <head> <title>414 Request-URI Too Large</title> </head> <body> <center> <h1>414 Request-URI Too Large</h1> </center> </body> </html> Description The GET request URL exceeds 2000 bytes.
415	Message { "code": "UNSUPPORTED_MEDIA_TYPE", "message": "'Content-Type: application/text' is not supported", "details": { "hint": "Our servers accept 'application/json' and 'application/graphql' types only." } Description The Content Type value provided for the Content-Type key is not supported.
422	Message { "code": "MAX_VARIANT_LIMIT_EXCEEDED", "message": "The maximum limit for variants in a single query is 3.", "details": { "hint": "Reduce the number of variants in the "x-cs-variant-uid" header to meet the allowed limit." } } Description The maximum number of variant UIDs that can be passed in the x-cs-variant-uid header is 3. To resolve this, reduce the number of variants to comply with the specified limit.
422	Message { "code": "SCHEMA_BUILD_ERROR", "message": "Unable to generate GraphQL types. Check details for more info.", "details": [ { "error": "The field 'product_refer_where' in 'product' content type, and 'product_refer_Where' from '__content_types' resulted in 'ProductReferWhere' GraphQL typename. Kindly update the field UIDs to continue querying." } ] } Description Due to conflicting field/content type UIDs, the server is unable to generate the GraphQL schema.
422	Message { "code":"MAX_EXTENSION_FETCH_LIMIT_EXCEEDED", "message": "Max allowed limit to retrieve extensions is '10', but the query requested '12'.", "details": { "hint": "The field 'extensionConnection' can fetch maximum '10' extensions." } } Description The maximum allowed limit for retrieving extensions via the extensionConnection field is 10.
422	Message { "code": "MAX_ROOT_FETCH_LIMIT_EXCEEDED", "message": "Max allowed limit to fetch a content types is '100'.", "details": { "hint": "The 'all_product' argument can fetch maximum '100' content types ." } Description The maximum allowed limit for retrieving content types is 100.
422	Message { "code": "INVALID_ARGUMENT", "message": "Invalid 'limit' argument value passed for 'all_product'.", "details": { "hint": "Expected argument is any number between [0 - 100]." } } Description The argument to be passed must be a numeric value between 0 and 100.
422	Message { "code": "PARSING_FAILED", "message": "Server failed to parse the request. Invalid query formatting.", "details": { "hint": "Kindly contact '[email protected]' with the query details." } } Description The server cannot process the request as the query format passed is incorrect.
422	Message { "code": "MAX_RESOLVER_COST_EXCEEDED", "message": "Max allowed cost per query is 20.Resolver cost calculated was 21.", "details": { "hint": "Reduce reference queries or use skip/limit arguments or limit content types at root level." } } Description The resolver cost per query exceeds the maximum allowed cost of 20.
422	Message { "code": "MAX_DB_COST_EXCEEDED", "message": "Exceeded max allowed database calls", "details": { "hint": "Try reducing reference queries or use skip/limit arguments or limit content types at root level." } } Description Your organization has exceeded the maximum limit of permitted database requests.
422	Message { "code": "REF_FILTER_DEPTH_EXCEEDED", "message": "Query filtering failed.", "details": { "hint": "The reference depth of the query filter has exceeded the limit allowed for your organization. " } Description You have exceeded the maximum allowed limit for the reference depth of the query filter.
422	Message { "code": "INVALID_BRANCH", "message": "The queried branch 'develop' is invalid.", "details": { "hint": "The requested branch does not exist in our database. For branch name and details, contact your stack administrator." } } Description The branch name you entered is either invalid or does not exist within this stack.
422	Message { "code": "INVALID_LOCALE", "message": "The queried locale 'en-uk' is invalid.", "details": { "hint": "Specify locale(s) available in your stack." } } Description The locale you entered is either invalid or does not exist within this stack.
422	Message { "code": "MAX_REFERENCE_DEPTH_LIMIT_EXCEEDED", "message": "Max allowed nested reference depth limit is '3', but the query has '5' nested references.", "details": { "hint": "Consider decreasing the number of nested references or contact '[email protected]' to request an increase in limits." } } Description The maximum allowed depth limit for retrieving nested referenced items (entries and assets) is three.
422	Message { "code": "MAX_DOCUMENT_LIMIT_EXCEEDED", "message": "Maximum allowed documents in a single query are '7500', but the query has requested '9234' documents.", "details": { "hint": "Consider reducing the number of queried references, utilizing skip/limit arguments for references, or contacting '[email protected]' to request an increase in limits." } } Description The maximum allowed limit for retrieving documents in a single GraphQL query is 7,500.
422	Message { "code": "MAX_ALLOWED_CONTENT_TYPE_LIMIT_EXCEEDED", "message": "Max allowed content types used in a query can be '100', but the query used '120' content types.", "details": { "hint": "Consider decreasing the number of reference fields being queried or contact '[email protected]' to request an increase in limits." } } Description You can retrieve a maximum of 100 content types in a single request.
422	Message { "code": "MAX_QUERIED_CONTENT_TYPE_LIMIT_EXCEEDED", "message": "`Maximum allowed content types queried at a time is 'THREE', but the query has requested 'FOUR' content types.", "details": { "hint": "Consider reducing the total number of queried content types or contact '[email protected]' to request an increase in the limits." } } Description The API request has exceeded the limit of maximum allowed content types queried in a single request, which is three by default.
422	Message { "code": "MAX_REFERENCE_LIMIT_EXCEEDED", "message": "Max allowed limit per reference for your organization is '100', but the query requested '120'.", "details": { "hint": "The 'referenceConnection' field has a limit of 100. Please provide a limit value between 0 and 100." } } Description You can retrieve a maximum of 100 referenced entries or assets in a single request by default.
500	Message { "code": "MAX_QUERIES", "message": "Only 1 query is allowed at a time.", "details": { "hint": "Include only one query in the request." } } Description You can include only one query in a request.
503	Message { "message": "Response size was too big. Maximum response size allowed is 7 MB.", "code": "RESPONSE_SIZE_TOO_BIG", "hint": "Consider using smaller queries or reducing the response size by utilizing 'limit' arguments." } Description The response size has exceeded the maximum limit of 7 MB.
504	Message { "code": "SERVICE_UNAVAILABLE", "message": "Request timeout! It seems the server is taking too long to process your request. Please try again." } Description The server is unable to process your request at this time. Please try again later.