Error Codes

REST API error codes and troubleshooting guide.

Error Code Reference

REST ad requests (/request) return one of the following codes in the code field of the response body.

code	msg	Description
0	OK	Success
4002	ERROR_CODE_AD_NO_FILL	No ad available for the request
4003	ERROR_CODE_INVALID_PARAMS	Required parameter (unit) missing or empty

If authentication fails, the API returns HTTP 401. See HTTP Status Codes.

• The msg field contains the constant name shown above, not a human-readable message. Handle errors based on the code value.
• REST ad requests do not return 4000 (ERROR_CODE_INVALID_UNIT) or 4001 (ERROR_CODE_AD_INACTIVE). An invalid ad unit ID or an ad unit without active campaigns also returns 4002.

---

Detailed Error Descriptions

ERROR_CODE_AD_NO_FILL (4002)

Cause: No ad can be served for the request. Common causes include:

• The ad unit ID is incorrect, or it belongs to a different app than the App Key
• The ad unit is not a banner or native ad unit
• There are no active ad campaigns for the ad unit
• The request does not match the campaigns’ targeting, including context targeting (contextId)

Solutions:

• Verify that the ad unit ID is correct and belongs to the same app as the App Key, and that no whitespace or special characters were included when copying
• Check that the ad unit is a banner or native ad unit
• Verify campaigns are running in the console, and check the campaign schedule (start/end dates) and budget
• Check that contextId exactly matches a Context ID entered in the console
• Check if targeting settings are too restrictive
• Implement retry logic (exponential backoff recommended)
• Prepare fallback content

{
    "code": 4002,
    "msg": "ERROR_CODE_AD_NO_FILL",
    "result": null
}

Retry Implementation Example:

async function requestAdWithRetry(params, maxRetries = 3) {
    for (let i = 0; i < maxRetries; i++) {
        try {
            const response = await axios.get('https://api-v2.adrop.io/request', {
                params,
                headers: { 'Authorization': 'YOUR_APP_KEY' }
            });

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

            if (response.data.code === 4002) {
                // No fill - retry
                await new Promise(r => setTimeout(r, Math.pow(2, i) * 1000));
                continue;
            }

            // Return immediately for other errors
            throw new Error(response.data.msg);
        } catch (error) {
            if (i === maxRetries - 1) throw error;
        }
    }

    return null; // Show fallback content
}

---

ERROR_CODE_INVALID_PARAMS (4003)

Cause: The required unit parameter is missing or empty.

Solutions:

• Verify the required parameter (unit) is included and has a value
• Ensure there are no typos in the parameter name

{
    "code": 4003,
    "msg": "ERROR_CODE_INVALID_PARAMS",
    "result": null
}

Parameter Checklist:

Parameter	Required	Valid Examples
unit	Required	AD_UNIT_123
pf	Recommended	android, ios, web
lcl	Recommended	ko_KR, en_US
theme	Optional	light, dark

---

Error Handling Best Practices

1. Handle Errors Based on Code

function handleAdResponse(response) {
    switch (response.code) {
        case 0:
            // Success - render ad
            renderAd(response.result);
            break;
        case 4002:
            // No ad available - show fallback content
            showFallbackContent();
            break;
        case 4003:
            // Parameter error - alert developers
            console.error('Invalid parameters:', response.msg);
            break;
        default:
            // Unknown error
            console.error('Unknown error:', response.code, response.msg);
    }
}

2. Prepare Fallback Content

function showFallbackContent() {
    const container = document.getElementById('ad-container');
    container.innerHTML = `
        <div class="fallback-content">
            <img src="/images/house-ad.jpg" alt="House Ad" />
        </div>
    `;
}

3. Monitoring and Logging

function logAdError(code, message, params) {
    // Monitor error rates
    analytics.track('ad_error', {
        error_code: code,
        error_message: message,
        unit_id: params.unit,
        timestamp: new Date().toISOString()
    });
}

---

HTTP Status Codes

The REST API also returns standard HTTP status codes.

HTTP Status	Description
200	Request successful (check response body for error code)
401	Authentication failed (verify App Key)
500	Internal server error

Always check the code value in the response body even for HTTP 200. Business logic errors are included in the response body.

---

Related Documentation

REST API Overview

Basic API usage

Targeting Settings

Configure targeting parameters