Status Codes and Error Responses

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

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 error is represented by the GraphQLErrorRepresentation type.

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.

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.

The 4XX status codes are less common for GraphQL. They can signify issues with your network or with your connection to a Salesforce org.

401 Unauthorized

The session ID or OAuth token has expired or is invalid. For more information on the error, review the message and errorCode descriptions in the response body.

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 can return a 404 error when a resource isn't found or is deleted. See the 200 OK section above for details.

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 could not be completed.

503 Service Unavailable

Too many requests in an hour or the server is down for maintenance. See Rate Limiting.