Status and error codes

GraphQL APIs handle errors differently from REST APIs, and the difference matters: you can't rely on HTTP status codes alone to detect failure. Always inspect the response body.

HTTP status codes

The most important thing to internalize: 200 OK does not mean your operation succeeded. GraphQL returns 200 even when:

• The operation hit an authorization check inside a resolver and was denied.
• The operation tried to update a record that didn't exist.
• A required field was null in the input.
• The resolver threw an exception.

In all of these cases, the HTTP status is 200 and the failure information is in the response body's errors array.

Response body shape

Every successful HTTP response (200) follows this shape:

{
  "data": { /* operation result, or null on hard failure */ },
  "errors": [ /* present when something went wrong; absent on full success */ ]
}

Three valid combinations:

// Full success
{ "data": { "getDataset": { "id": "abc", "name": "Sales" } } }

// Hard failure — no data returned
{
  "data": null,
  "errors": [
    { "errorType": "Unauthorized", "message": "Not authorized to access getDataset on type Query" }
  ]
}

// Partial success — some fields returned, others failed
{
  "data": { "getDataset": { "id": "abc", "name": "Sales", "owner": null } },
  "errors": [
    { "path": ["getDataset", "owner"], "errorType": "ResolverFailure", "message": "User lookup timed out" }
  ]
}

The third case is GraphQL-specific and worth handling deliberately. A request can be both successful (you got data) and failed (some fields didn't resolve) at the same time. For most non-critical fields this is fine — render what you got. For critical fields, treat any non-empty errors array as a failure.

Common error types

Every error object has an errorType field that classifies the failure. Handle these explicitly:

Less common types you might see:

• BadRequestException — the GraphQL document parsed but referenced fields that don't exist (schema mismatch).
• PaginationOverflow — you've requested too many items per page; reduce limit.
• NotImplemented — operation is documented but not yet enabled in your environment.

Handling errors in code

A robust client checks both the HTTP status and the errors array:

async function callBeem(query, variables) {
  const res = await fetch('https://api.beemdata.com/graphql', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${token}`,
    },
    body: JSON.stringify({ query, variables }),
  });

  if (res.status === 401) {
    throw new AuthError('Token expired or invalid');
  }
  if (res.status === 429) {
    throw new RateLimitError('Throttled');
  }
  if (!res.ok) {
    throw new Error(`HTTP ${res.status}`);
  }

  const body = await res.json();

  if (body.errors && body.errors.length > 0) {
    // Partial successes are still in body.data; decide per use case.
    const types = body.errors.map(e => e.errorType);
    if (types.includes('UnauthorizedException')) throw new AuthError('Token expired');
    if (types.includes('ThrottlingException'))   throw new RateLimitError('Throttled');
    throw new ApiError(body.errors);
  }

  return body.data;
}

The pattern matters: don't just call res.json() and hand the result to your application. Inspect errors first.

Reporting issues

If you see an error that isn't documented here or behaves unexpectedly, capture the full response body (including the errors array, the path if present, and any errorInfo object) and contact [email protected].