Status Codes and Error Responses

GraphQL API queries return HTTP status codes or error responses that describe the query status.

200 OK

Success with HTTP POST request. The response contains the query result. GraphQL API can also return a 200 OK in cases where the request contains an error, such as an invalid object name or field. The GraphQLErrorRepresentation type represents the error.

1{
2  "data": {},
3  "errors": [
4    {
5      "extensions": {
6        "ErrorType": "ValidationError"
7      },
8      "locations": [
9        {
10          "column": 7,
11          "line": 4
12        }
13      ],
14      "message": "Validation error of type FieldUndefined: Field &#39;Accounts&#39; in type &#39;RecordQuery&#39; is undefined @ &#39;uiapi/query/Accounts&#39;",
15      "paths": []
16    }
17  ]
18}

A 200 OK status code is returned even if the query doesn’t return any matching items or if you pass in an invalid record ID.

1{
2    "data": {
3        "uiapi": {
4            "query": {
5                "Case": {
6                    "edges": []
7                }
8            }
9        }
10    },
11    "errors": []
12}

The ErrorType field returns one of these errors.

InvalidSyntax - The request contains a syntax error.
ValidationError - The request isn’t valid against the GraphQL API schema. For example, this error can occur if an object or field name included in the query doesn’t exist.
DataFetchingException - An exception occurred while fetching data, for example, invalid credentials.
OperationNotSupported - Although the request is valid against the GraphQL API schema and successfully parsed, the server can’t resolve which operation to run.
ExecutionAborted - The request didn’t complete successfully.

4XX Status Codes

The 4XX status codes signify issues with your network, connection to a Salesforce org, or access to GraphQL API.

401 Unauthorized: The session ID or OAuth token has expired or is invalid. For more information about the error, review the message and errorCode descriptions in the response body.
403 Forbidden: Unauthenticated guest users don’t have access to GraphQL API in the org. Starting in API v67.0, admins can turn on guest user access from Setup. In the Quick Find box, enter and select API Access Controls, and then turn on guest user access.
404 Not Found: The specified endpoint wasn’t found. Only the graphql endpoint is supported.

GraphQL API usually returns a 200 OK status code even if a record isn’t found or is deleted. Contrastingly, UI API returns a 404 error if a resource isn’t found or is deleted. See the previous 200 OK section for details.

Note

5XX Status Codes

5XX status codes usually mean there’s an internal Salesforce error. To resolve this issue, try your request again or contact Salesforce Customer Support if the issue persists.

500 Internal Server Error: An error has occurred within Lightning Platform, so the request didn’t complete.
503 Service Unavailable: Too many requests in an hour or the server is down for maintenance. See Rate Limiting.