GraphQL Error Reference

Understanding GraphQL Errors

Unlike REST APIs where HTTP status codes indicate errors, GraphQL API requests typically return a HTTP 200 OK status code even when errors occur. Instead, errors are included in the response body within an errors array.

{
  "errors": [
    {
      "message": "Error message",
      "path": ["field", "path"],
      "extensions": {
        "code": "ERROR_CODE"
      }
    }
  ]
}

HTTP Status Codes

While GraphQL responses usually have a 200 status code, you may occasionally encounter these HTTP status codes:

Status Code	Name	Description
200, 201	OK	The request was successful, but may contain errors in the response body
400	Bad Request	The request is malformed or invalid GraphQL syntax
401	Unauthorized	Missing or invalid API key
402	Payment Required	API key has consumed all available API credits.
403	Forbidden	Valid API key but insufficient permissions for the request
413	Payload Too Large	Request body exceeds size limits
429	Too Many Requests	Rate limit exceeded
500	Internal Server Error	Server-side error occurred

Handling Errors in Your Application

When working with our GraphQL API, we recommend implementing these error handling practices:

1. Always check for the presence of an errors array in the response
2. Look at both the message and the extensions.code to determine the type of error
3. Implement appropriate retry logic for transient errors (timeouts, service unavailable)
4. Log detailed error information for debugging purposes

Need Help?

If you're experiencing persistent errors or need assistance debugging an issue :

1. Ensure you're using the latest version of our documentation
2. Contact [email protected] for support