Expand GraphQL API error documentation with service unavailability, auth, and internal errors (#28446)

* DS-15448: expand GraphQL API error documentation with service unavailability, auth, and internal errors

* DS-15448: address review comments, add error codes and link to token docs

---------

Co-authored-by: Tom Benn <tbenn@cloudflare.com>

Author: fridgecow

src/content/docs/analytics/graphql-api/errors.mdx

@@ -33,32 +33,67 @@ All responses contain an `errors` array, which will be `null` if there are no er
 
 ## Common error types
 
+### Service unavailability
+
+Sample error messages:
+
+* `unable to execute query, please try again later` (HTTP `503`)
+* `too many queries in progress, please try again later` (HTTP `503`)
+
+These messages indicate a temporary server-side issue. The first message typically means the upstream database is unreachable or returned an error. The second message means the server has reached its maximum number of concurrent queries.
+
+Retry the request after a short delay. If the error persists, check the [Cloudflare status page](https://www.cloudflarestatus.com/) for ongoing incidents.
+
 ### Dataset accessibility limits exceeded
 
 Sample error messages:
 
-* "cannot request data older than..."
-* "number of fields cannot be more than..."
-* "does not have access to the path..."
-* "not available for your plan. Upgrade to..."
+* `cannot request data older than...` (HTTP `400`)
+* `number of fields can't be more than...` (HTTP `400`)
+* `limit must be positive number and not greater than...` (HTTP `400`)
+* `query time range is too large...` (HTTP `400`)
 
 These messages indicate that the query exceeds what is allowed for the particular dataset under the current [plan](https://www.cloudflare.com/plans/), and an upgrade should be considered. Refer to [Node limits](/analytics/graphql-api/limits/#node-limits-and-availability) for details.
 
 ### Parsing issues
 
 Sample error messages:
 
-* "error parsing args..."
-* "scalar fields must have not selections"
+* `error parsing args...` (HTTP `400`)
+* `scalar fields must have no selections` (HTTP `400`)
+* `object field must have selections` (HTTP `400`)
+* `unknown field...` (HTTP `400`)
+* `query contains error, please review it and retry` (HTTP `400`)
 
-These messages indicate that the query cannot be processed because it is malformed.
+These messages indicate that the query cannot be processed because it is malformed. Check the query syntax against the [GraphQL schema](/analytics/graphql-api/getting-started/explore-graphql-schema/) and correct the invalid fields or structure.
 
 ### Rate limits exceeded
 
 Sample error messages:
 
-* "limit reached, please try reduced time period"
-* "quota exceeded, please repeat your request in the next minute"
-* "rate limiter budget depleted, try again after 5 minutes"
+* `rate limiter budget depleted, try again after 5 minutes` (HTTP `429`)
+* `in combination, your request queries too many nodes, zones and accounts` (HTTP `429`)
+* `query consumed excessive resources, please try running smaller queries which consume fewer resources` (HTTP `429`)
+
+These messages indicate the query exceeded rate or resource limits. Reduce the query complexity, the number of zones or accounts per request, or wait before retrying. Refer to the [Limits](/analytics/graphql-api/limits/) section for more details about rate limits.
+
+### Authentication and authorization errors
+
+Sample error messages:
+
+* `Unauthorized` (HTTP `401`)
+* `not authorized for that account` (HTTP `403`)
+* `zones [...] are not authorized` (HTTP `403`)
+* `does not have access to the path...` (HTTP `403`)
+
+An `Unauthorized` response means the API token or bearer token is missing, expired, or invalid. Verify that you are passing a valid token in the `Authorization` header.
+
+A `403` response means the token does not have the required permissions for the requested account or zone. Verify the token has the **Analytics: Read** permission for the relevant resources. Refer to the [Tokens](/fundamentals/api/get-started/create-token/) section for more details.
+
+### Internal server errors
+
+Sample error message:
+
+* `Internal server error` (HTTP `500`)
 
-Refer to the [Limits](/analytics/graphql-api/limits/) section for more details about rate limits.
+This is a generic error indicating an unexpected failure. If it persists, contact [Cloudflare Support](https://support.cloudflare.com/) with the full request and response, including the `Ray-ID` header from the HTTP response.