Learn how to handle errors and follow best practices when using the BuildBetter GraphQL API.
"errors"
array in the JSON response). Here are some common error scenarios and how to address them:
Authorization
or X-Buildbetter-API-Key
header is present and correct. If you see an error like "Not authorized"
or a similar message, double-check your credentials. Also, if you are using a shared link key, make sure you are querying the specific allowed data (for example, a shared document key cannot be used to fetch a different document)."permission denied for table 'interview'"
if you tried to access a resource outside your scope. The solution is to ensure you’re querying IDs that belong to your organization or have the proper share key for that object. If you believe you should have access, check that your user has the necessary permissions in the BuildBetter app (or contact an admin)."errors"
array in the response will contain message fields that guide you to the problem. During development, using a GraphQL client or IDE can help catch errors early (for example, GraphiQL or Apollo Studio will underline unknown fields or type mismatches). By carefully reading error messages and following the documentation, you can resolve most issues quickly.
where
filters and pagination parameters (limit
and offset
) to limit how much data is returned. Fetch data in chunks rather than one huge query. For instance, to get calls in pages of 50, you can query interview(limit: 50, offset: 0)
for the first page, then offset: 50
for the next, and so on. Similarly, filter by date or other criteria to narrow results if applicable (e.g., only calls after a certain date).
...CallBasicFields
in any query where you need those fields. Fragments are especially useful if your application has predefined data patterns (the BuildBetter frontend uses fragments to keep field selections consistent across different queries for calls, signals, etc. ).
order_by
) and basic aggregations. If you need the data sorted or some aggregate like count, let the server do it if possible, instead of retrieving everything and sorting on the client. For example, use order_by: { created_at: desc }
rather than fetching unsorted data and ordering in your code. To get a count of items, you can use the _aggregate
fields that Hasura provides (for instance, interview_aggregate { aggregate { count } }
will return the number of calls). This prevents you from fetching all records just to count them.