Error Codes

Overview

This document provides a comprehensive list of error codes that may be returned by the Monday API. Understanding these error codes will help you handle errors appropriately in your application.

HTTP Status Codes

2xx Success

Code	Description
200	OK - Request successful
201	Created - Resource created successfully

4xx Client Errors

Code	Description
400	Bad Request - Invalid request parameters or malformed request
401	Unauthorized - Invalid or missing API key, or signature verification failed
403	Forbidden - Access denied, insufficient permissions, or account restrictions
404	Not Found - Resource not found or endpoint does not exist
405	Method Not Allowed - HTTP method not supported for this endpoint
409	Conflict - Request conflicts with current state of the resource
422	Unprocessable Entity - Request validation failed
429	Too Many Requests - Rate limit exceeded

5xx Server Errors

Code	Description
500	Internal Server Error - Server encountered an unexpected error
502	Bad Gateway - Server received an invalid response from upstream
503	Service Unavailable - Server is temporarily unavailable
504	Gateway Timeout - Server did not receive a timely response from upstream

Error Response Format

All error responses follow this standard format:

{
    "code": 400,
    "msg": "invalid request parameters",
    "data": null,
    "requestId": "288cbcb2-2f24-4d1f-9b9f-38787bc14258"
}

Response Fields

Field	Type	Description
code	number	HTTP status code (same as HTTP response code)
msg	string	Human-readable error message
data	object	Response data (null for error responses)
requestId	string	Request ID for tracking

Success Response Format

Success responses use code: 0:

{
    "code": 0,
    "msg": "",
    "data": {
        // Response data
    },
    "requestId": "288cbcb2-2f24-4d1f-9b9f-38787bc14258"
}

Error Handling Best Practices

1. Check Response Status

Always check the code field in the response:

if (response.code !== 0) {
    console.error(`API Error ${response.code}: ${response.msg}`);
    // Handle specific error based on HTTP status code
    handleError(response.code, response.msg);
}

2. Implement Retry Logic

For transient errors (5xx), implement retry logic:

async function apiCallWithRetry(url, options, maxRetries = 3) {
    for (let i = 0; i < maxRetries; i++) {
        try {
            const response = await fetch(url, options);
            const data = await response.json();

            if (data.code === 0) {
                return data;
            }

            // Retry for server errors (5xx)
            if (shouldRetry(data.code) && i < maxRetries - 1) {
                await new Promise((resolve) =>
                    setTimeout(resolve, 1000 * (i + 1))
                );
                continue;
            }

            throw new Error(`API Error: ${data.msg}`);
        } catch (error) {
            if (i === maxRetries - 1) throw error;
            await new Promise((resolve) => setTimeout(resolve, 1000 * (i + 1)));
        }
    }
}

function shouldRetry(httpStatusCode) {
    // Retry for server errors (500, 502, 503, 504)
    return httpStatusCode >= 500 && httpStatusCode < 600;
}

3. Log Errors Appropriately

Implement proper error logging:

function logError(httpStatusCode, errorMessage, requestData) {
    const errorLog = {
        timestamp: new Date().toISOString(),
        httpStatusCode,
        errorMessage,
        requestData,
        severity: getErrorSeverity(httpStatusCode),
    };

    console.error("API Error:", errorLog);

    // Send to monitoring service for critical errors
    if (errorLog.severity === "critical") {
        sendToMonitoring(errorLog);
    }
}

function getErrorSeverity(httpStatusCode) {
    if (httpStatusCode >= 500) return "critical";
    if (httpStatusCode >= 400 && httpStatusCode < 500) return "high";
    return "medium";
}

4. User-Friendly Error Messages

Provide user-friendly error messages based on HTTP status codes:

function getUserFriendlyMessage(httpStatusCode, errorMessage) {
    const errorMessages = {
        400: "Invalid request. Please check your parameters.",
        401: "Authentication failed. Please check your API credentials.",
        403: "Access denied. You don't have permission for this operation.",
        404: "Resource not found.",
        429: "Too many requests. Please slow down and try again later.",
        500: "Internal server error. Please try again later.",
        502: "Bad gateway. Please try again later.",
        503: "Service unavailable. Please try again later.",
        504: "Gateway timeout. Please try again later.",
    };

    return errorMessages[httpStatusCode] || errorMessage || "An unexpected error occurred";
}

Rate Limiting Errors

When rate limits are exceeded, you will receive HTTP 429 status code:

{
    "code": 429,
    "msg": "Too Many Requests",
    "data": null,
    "requestId": "288cbcb2-2f24-4d1f-9b9f-38787bc14258"
}

Rate Limit Headers

Check response headers for rate limit information:

const response = await fetch(url, options);
const rateLimitRemaining = response.headers.get("X-RateLimit-Remaining");
const rateLimitReset = response.headers.get("X-RateLimit-Reset");

console.log(`Remaining requests: ${rateLimitRemaining}`);
console.log(`Rate limit resets at: ${new Date(rateLimitReset * 1000)}`);

Common Error Scenarios

1. Authentication Failures (401)

{
    "code": 401,
    "msg": "Unauthorized",
    "data": null,
    "requestId": "288cbcb2-2f24-4d1f-9b9f-38787bc14258"
}

Common causes:

• Missing API authentication headers (X-ACCESS-KEY, X-ACCESS-SIGN, X-ACCESS-TIMESTAMP, X-ACCESS-PASSPHRASE)

• Incorrect API secret key

• Wrong timestamp format

• Incorrect signature generation

• Timestamp outside valid time window

2. Parameter Validation Errors (400)

{
    "code": 400,
    "msg": "invalid request parameters",
    "data": null,
    "requestId": "288cbcb2-2f24-4d1f-9b9f-38787bc14258"
}

Common causes:

• Missing required parameters

• Invalid parameter values

• Incorrect parameter format

• Out-of-range values

• Invalid symbol or address format

3. Server Errors (500)

{
    "code": 500,
    "msg": "Internal Server Error",
    "data": null,
    "requestId": "288cbcb2-2f24-4d1f-9b9f-38787bc14258"
}

Common causes:

• Internal server error

• Service unavailable

• Database connection issues

• Upstream service failures

Troubleshooting Guide

Step 1: Verify Request Format

• Check HTTP method (GET, POST, etc.)

• Verify endpoint URL

• Ensure all required headers are present

• Validate request body format (if applicable)

Step 2: Check Authentication

• Verify API key is correct and active

• Ensure signature is generated correctly

• Check timestamp is within valid range

• Verify IP address is whitelisted (if applicable)

Step 3: Validate Parameters

• Check all required parameters are present

• Verify parameter values are within valid ranges

• Ensure parameter formats are correct

• Check for any deprecated parameters

Step 4: Check Account Status

• Verify account is active and not suspended

• Check account permissions for the requested operation

• Ensure sufficient balance (for trading operations)

• Verify account type is correct

Step 5: Monitor System Status

• Check for any ongoing maintenance

• Verify system is operational

• Check rate limit status

• Monitor for any service disruptions

Support

If you continue to experience issues:

1. Check the Quick Start Guide for basic setup

2. Review individual API documentation files

3. Verify your implementation matches the examples

4. Contact support with specific error codes and request details

Error Code Updates

This error code list is updated regularly. Always refer to the latest version for the most current error codes and descriptions.