Error handling
If your API request cannot be completed successfully, you will receive an error message.
Error format
The error format depends on which version you are using.
Version 2025-01
2025-01
Starting in version 2025-01
, errors returned by the API will have the following characteristics:
- HTTP status: Response will be
200 – OK
for application-level errors. Other statuses will be returned for transport-layer errors, such as500 - Internal server error
,429 - Too many requests
or400 - Bad request
- JSON response: Body will contain an
errors
array with further details about each error - Partial data: Requests will return partial data, so the
data
object may also contain some information. For example, if you query 3 fields, you may get two back and one error. Retry-After
header: Errors will include theRetry-After
header to indicate how long you need to wait before making another request
Sample format
Here's an example of an application-level error:
{
"data" : [],
"errors": [
{
"message": "User unauthorized to perform action",
"locations": [
{
"line": 2,
"column": 3
}
],
"path": [
"me"
],
"extensions": {
"code": "UserUnauthorizedException",
"error_data": {},
"status_code": 403
}
}
],
"account_id": 123456
}
{
"data": {
"me": {
"id": "4012689",
"photo_thumb": null
},
"complexity": {
"query": 12
}
},
"errors": [
{
"message": "Photo unavailable.",
"locations": [
{
"line": 4,
"column": 5
}
],
"path": [
"me",
"photo_thumb"
],
"extensions": {
"code": "ASSET_UNAVAILABLE"
}
}
],
"account_id": 18888528
}
Developing a new application?
Start with version
2025-01
to take advantage of simplified error responses. Pass a version name with your API calls to enable the unified error format.
Versions 2024-10
and earlier
2024-10
and earlierVersions of the API before 2024-10
return 3 different JSON formats for different errors. These are unified in version 2025-01
.
Error format
Check out the tabs below for the different possible formats in 2024-10
(legacy) and 2025-01
(updated).
# Error structure in 2024-10 and earlier
{
"errors": [
{
"message": "Parse error on \")\" (RPAREN) at [59, 15]",
"locations": [
{
"line": 59,
"column": 15
}
]
}
],
"account_id": 1234567890
}
# Error structure in 2024-10 and earlier
{
"errors": [
{
"message": "User unauthorized to perform action",
"locations": [
{
"line": 2,
"column": 3
}
],
"path": [
"me"
],
"extensions": {
"code": "UserUnauthorizedException",
"error_data": {},
"status_code": 403
}
}
],
"error_message": "User unauthorized to perform action",
"error_code": "UserUnauthorizedException",
"error_data": {},
"status_code": 403,
"account_id": 123456
}
# Error structure in 2024-10 and earlier
{
"error_message": "Internal server error",
"status_code": 500
}
# Error structure in 2025-01 onwards
{
"data" : [],
"errors": [
{
"message": "User unauthorized to perform action",
"locations": [
{
"line": 2,
"column": 3
}
],
"path": [
"me"
],
"extensions": {
"code": "UserUnauthorizedException",
"error_data": {},
"status_code": 403
}
}
],
"account_id": 123456
}
Errors by status code
2xx errors
Errors with a 2xx status code indicate that monday.com is not accepting the requested action due to a platform platform restriction, limitation, or rule. These errors occur for various reasons, including passing invalid values, missing permissions, or reaching character limits.
Here are some of the most common errors:
Error code | HTTP status code | Description | Resolution |
---|---|---|---|
API_TEMPORARILY_BLOCKED | 200 | There is an issue with the API and usage has temporarily been blocked | Check the status page for updates and retry your call once the issue has been resolved. |
ColumnValueException | 200 | Incorrect column value formatting | |
CorrectedValueException | 200 | The query is of the wrong type | If you try to update a column with simple values (String values), ensure the column supports this type of value format |
CreateBoardException | 200 | Error in your create board mutation | |
InvalidArgumentException | 200 | The argument being passed in the query is invalid or you've hit a pagination limit | |
InvalidBoardIdException | 200 | The board ID being passed in the query is invalid | Verify that the board ID exists and you have access to it |
InvalidColumnIdException | 200 | The column ID being passed in the query is invalid | Verify that the column ID exists and you have access to it |
InvalidUserIdException | 200 | The user ID being passed in the query is invalid | Verify that the user ID exists and the user is assigned to your board |
InvalidVersionException | 200 | The requested API version is invalid | Ensure that your request follows the proper format |
ItemNameTooLongException | 200 | The item name has exceeded the allotted number of characters | Ensure the item name is 1-255 characters |
ItemsLimitationException | 200 | You have exceeded the limit of 10,000 items per board | Reduce the number of items on the board |
missingRequiredPermissions | 200 | The operation has exceeded the OAuth permission scopes granted for the app | Review your app's permission scopes to ensure the correct ones are requested |
Parse error on... | 200 | Incorrect query string formatting | |
ResourceNotFoundException | 200 | The ID being passed in your query is invalid | Verify that the ID of the item, group, or board you’re querying exists |
4xx client errors
Errors with a 4xx status code indicate that something went wrong on the client's (your) side. These errors occur for various reasons, including not having access to the requested information, using the API at too high a volume, or providing incorrect input.
Here are some of the most common errors:
Error | HTTP status code | Description | Resolution |
---|---|---|---|
Bad request | 400 | The structure of your query string was passed incorrectly | query key |
JsonParseException | 400 | Issues interpreting the provided JSON | Verify all JSON is valid using a JSON validator (e.g., JSON lint ) |
Unauthorized | 401 | You don't have permission to access the data | Authorization header |
Your ip is restricted | 401 | An account admin has restricted access to the system from specific IP addresses | Confirm that your IP address is not restricted by your account admin |
UserUnauthorizedException | 403 | The user doesn't have the required permission to perform the action in question | Verify that the user has permission to access or edit the given resource |
ResourceNotFoundException | 404 | The ID being passed in the query is invalid | Verify that the ID of the user you are querying exists and is assigned to your board |
DeleteLastGroupException | 409 | The last group on a board is being deleted or archived | Verify that you have at least one group on the board |
RecordValidException | 422 | Indicates one of the following: - A board has exceeded 400 individual subscribers or 100 team subscribers - A user or team has subscribed to more than 10,000 boards | |
ComplexityException | 429 | You have reached the complexity limit | limits and page arguments |
maxConcurrencyExceeded | 429 | You exceeded the maximum number of queries allowed at once | |
Rate Limit Exceeded | 429 | You made more than 5,000 requests in one minute | Reduce the number of requests sent in one minute |
5xx server errors
Errors with a 5xx status code indicate that something went wrong on the server (monday's) side.
Here are some of the most common errors:
Error | HTTP status code | Description | Resolution |
---|---|---|---|
Internal Server Error | 500 | Indicates that something went wrong. Common causes are: - Invalid arguments, such as board or item IDs that don't exist - Malformatted JSON column values |
Join our developer community!
We've created a community specifically for our devs where you can search through previous topics to find solutions, ask new questions, hear about new features and updates, and learn tips and tricks from other devs. Come join in on the fun! 😎
Updated 6 days ago