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

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 as 500 - Internal server error, 429 - Too many requests or 400 - 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 the Retry-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

Versions 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 codeHTTP status codeDescriptionResolution
API_TEMPORARILY_BLOCKED200There is an issue with the API and usage has temporarily been blockedCheck the status page for updates and retry your call once the issue has been resolved.
ColumnValueException200Incorrect column value formatting
  • Ensure the column is supported by our API and not calculated in the client
  • Verify that the column value conforms with each column's data structure
  • Check that the connect boards column you're referencing is connected to a board via the monday.com UI
  • CorrectedValueException200The query is of the wrong typeIf you try to update a column with simple values (String values), ensure the column supports this type of value format
    CreateBoardException200Error in your create board mutation
  • If you’re creating a board from a template, ensure the template ID is a valid monday template or a board that has template status. To learn more about making a board a template, check out our resource on board templates here
  • If you’re duplicating a board, ensure the board ID exists
  • InvalidArgumentException200The argument being passed in the query is invalid or you've hit a pagination limit
  • Check your argument for typos
  • Verify that the argument exists for the object you are querying
  • Make your result window smaller
  • InvalidBoardIdException200The board ID being passed in the query is invalidVerify that the board ID exists and you have access to it
    InvalidColumnIdException200The column ID being passed in the query is invalidVerify that the column ID exists and you have access to it
    InvalidUserIdException200The user ID being passed in the query is invalidVerify that the user ID exists and the user is assigned to your board
    InvalidVersionException200The requested API version is invalidEnsure that your request follows the proper format
    ItemNameTooLongException200The item name has exceeded the allotted number of charactersEnsure the item name is 1-255 characters
    ItemsLimitationException200You have exceeded the limit of 10,000 items per boardReduce the number of items on the board
    missingRequiredPermissions200The operation has exceeded the OAuth permission scopes granted for the appReview your app's permission scopes to ensure the correct ones are requested
    Parse error on...200Incorrect query string formatting
  • Verify that all strings are valid in your query
  • Close all parenthesis, brackets, and curly brackets
  • ResourceNotFoundException200The ID being passed in your query is invalidVerify 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:

    ErrorHTTP status codeDescriptionResolution
    Bad request400The structure of your query string was passed incorrectly
  • Pass your query string with the query key
  • Send your request as a POST request with a JSON body
  • Avoid unterminated strings in your query
  • JsonParseException400Issues interpreting the provided JSONVerify all JSON is valid using a JSON validator (e.g., JSON lint )
    Unauthorized401You don't have permission to access the data
  • Input a valid API key
  • Pass the key in the Authorization header
  • Your ip is restricted401An account admin has restricted access to the system from specific IP addressesConfirm that your IP address is not restricted by your account admin
    UserUnauthorizedException403The user doesn't have the required permission to perform the action in questionVerify that the user has permission to access or edit the given resource
    ResourceNotFoundException404The ID being passed in the query is invalidVerify that the ID of the user you are querying exists and is assigned to your board
    DeleteLastGroupException409The last group on a board is being deleted or archivedVerify that you have at least one group on the board
    RecordValidException422Indicates 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
  • Learn how to optimize board subscribers
  • Unsubscribe from, delete, or archive irrelevant boards
  • ComplexityException429You have reached the complexity limit
  • Utilize the limits and page arguments
  • Only request the information you need
  • Read more about rate limits
  • maxConcurrencyExceeded429You exceeded the maximum number of queries allowed at once
  • Reduce the number of queries sent at once
  • Use a retry mechanism in your code
  • Rate Limit Exceeded429You made more than 5,000 requests in one minuteReduce 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:

    ErrorHTTP status codeDescriptionResolution
    Internal Server Error500Indicates that something went wrong. Common causes are:

    - Invalid arguments, such as board or item IDs that don't exist
    - Malformatted JSON column values
  • Retry your request after a short period
  • Double-check your request's format
  • Ensure your API token has the right permissions
  • 📘

    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! 😎