Troubleshooting Tips & Tricks for issues with the API
Hello awesome dev community! It’s Alex from monday.com’s developer success team again. If you ever find yourself stuck with an API call that just doesn’t seem to be working, this is the right place to be. Today, I wanted to share some general guidelines on how you could troubleshoot an API call to monday.com, and the basic steps to take in order to isolate the behavior further. We’ll go through the following steps together: Troubleshooting an API call on the API playground; Troubleshooting an API call made as an HTTP request; Limitations you should keep in mind Where to get additional help, if all else fails How do I troubleshoot API calls? This guide goes through a few different ways you can troubleshoot your API calls. These are basic steps you can take into account if something doesn’t seem to be working. You can use this guide to figure out the best next course of action. Part 1: The API call does not work in the Developer Playground As a user of monday.com, you have access to a testing environment to play with the API without needing to build their own environment. You can access it by going to the Developers section, found in “My Profile”: You can then choose the Developer Playground in the top menu to enter your account’s API test environment: Here, you can test queries, as well as mutations to see what data each query returns without having to package it in an HTTP request. If your query works in the testing environment, then we know the issue is probably with how you’re sending data to the server. Feel free to scroll right ahead to part 2 🙂 Part 1a: Argument X on field Y has an invalid value. This error means that the server expects a certain type of value (such as a number or text string) but is receiving a different type. Check the data you are trying to pass for that field, and what the server expects (via our documentation). Here’s an example: Since we are sending an integer to a text column, which normally expects Strings, we get an innvalid value error. If we send the same value (3) formatted as a JSON string, that will work: Part 1b: Field X does not exist on Type Y You might be trying to change a value that doesn’t exist, or make a query that doesn’t exist. For example here’s a query that doesn’t work just yet, since the “subitem” argument for board_kind doesn’t exist: Please check the spelling of the fields in the query. Part 1c: Parse Error on X This means there’s an issue with the commas and brackets of the query. Make sure the brackets are balanced and there are commas between the fields of each query 🙂 For example, there is an extra right curly bracket in the query below: Part 1d: 500 Internal Server Error This is a generic error that could be caused by a number of issues with your query – it’s basically a catch-all error for all the other issues that can crop up. If you get an Internal Server Error, check the following: Do you happen to have extra commas or brackets in the query? Is there a chance you are trying to get a board that doesn’t exist? Could it be that your API call is attempting to get an item that doesn’t exist? Or perhaps there’s a chance your API call is querying for a column that doesn’t exist? Part 2: It works in the testing environment, but not in my application 😦 If the query works in the testing environment but is failing in your custom application, there are a few quick troubleshooting steps we can do to ensure you are sending the correct information. Part 2a: Is the query exactly the same as in the testing environment? Sometimes, things can go wrong by accident in the weirdest of places. Sometimes, the query is just not copypasted fully. If you are creating your query through code that dynamically populates a query in your application, it might make sense to first test the exact query you are planning to use in the testing environment. If this works, then we know the issue is in how your data is being sliced-and-diced to generate your final API call. Part 2b: Are you sending the request to the right place? All API requests are sent to our server as an HTTP request. HTTP requests are the basic protocol used for almost all, if not all interactions on the modern internet. Requests to our API must be POST requests (signifying they want to change data). This applies to both queries and mutations. Note: although GET works for some queries, POST is still the best-practice method for this. Sent to https://api.monday.com/v2 for queries and mutations, or the File endpoint if you are trying to upload a file - api.monday.com/v2/file Part 2c: Are you passing the correct headers? HTTP requests are made of two chunks of data – headers and a body. The header contains metadata about the request itself; it tells the server “Heads up! This is the kind of data I’m sending you.” The body is where the actual content of the request is. There are two headers, in particular, that are required to be sent with any API request. One is the “Authorization” header, which supplies the API key, and the other is “Content-Type”, which tells the server the format of the data in the body. Please make sure you are passing the following in as headers: { “Content-Type” : “application/json”, “Authorization” : “mySuperSecretAPIKey” } Part 2d: Is the request body formatted correctly? You will need to make sure you are passing the query correctly. In the Body of your HTTP request, you will need to declare that what you are sending is a “query”, and this applies to both queries (getting data) and mutations (changing data). You will just declare further that the query you are sending is a mutation later down the line. An example of a query to search your board’s items for column values in Postman: In case you are sending a mutation, that has to be included in the body of the API call: Part 2e: I’m still getting an error. Now what? If you’ve followed the above instructions and are still getting an error, there might be a problem with how your query is structured. You can check out the Errors section of our API documentation - perhaps that can help figure out what is going astray. Part 3: Things to be aware of: Part 3a: Unsupported column types: If your API call takes over a minute to process, you will be faced with a timeout. In those cases, try and see if you can reformat the call to be more lightweight - getting the same data in multiple calls via pagination, for example. Another thing to check is making sure that the user that generated your API token has access to the board you are attempting to query. If you receive an empty object as a response from a “boards” query, most likely there is something astray with the access permissions. Some column types are not supported by our API, or are supported to a limited extent. Here is a list that can help you as a reference point: Columns you cannot read or update via the API Progress tracking Auto number column Columns that you can read using a workaround Item ID column – you cannot get the data in the column, but you can check the ID of the item via the API; Last updated column – you can get the time an item was edited via the activity log queries; Creation log column – you can check the creation date of the item via the API; Formula column - you can read the formula configuration (using settings_str), and then calculate the formula values in your application code. Columns without write support TIME TRACKING:. You cannot edit the data, or start/stop the timer. Part 3b: Items_by_column_values limitations: You can not query for null values just yet; It is not possible to query multiple columns at the same time; It is not possible to query for multiple values (for example, array of user IDs to search for in a People column); The items_by_column_values query does not support every single column type. Generally, if a column can contain multiple values (dropdown, people, tags), it cannot be filtered. To populate the Numbers column with a “0” value, you might need to format your column values as a String, and not as an integer. You can also take a look at the Errors section in our documentation to find more info on the errors our API might throw, as well as some general steps you can take to troubleshoot. Part 3c: List dimension mismatch on variable $theboardid and argument ids (Int! / [Int]) At the time, the board IDs field will expect an array/list of Ids. If you are sending a single ID, you’ll need to declare your variable as an array. Here are 2 examples that can illustrate the point a little further: This is an example of a query that won’t work: query ($boardId:Int) { boards (ids:$boardId) { items(ids:162169283) { column_values(ids:"time_tracking") { value } } } } This query will work instead! Notice how the board ID variable is declared as an array of integers with [Int]: query ($boardId:[Int]) { boards (ids:$boardId) { items(ids:162169283) { column_values(ids:"time_tracking") { value } } } } Part 4: Getting additional help If the above steps haven’t solved the issue, please feel free to reach out to us in the community or by using our appsupport@monday.com inbox - we’d be happy to help!
