RTB API

Using merchenta.io for real-time bidding

Error codes 

Validation errors will be returned as part of standardized JSON formatted HTTP response body when we cannot process the API call. All validation errors have a code and a message. The code is intended for programmatic consumption and the message is human-readable.

Response structure

RTB API separates responses into some basic types, and defines required and optional keys for each type:

Type Description Required Keys Optional Keys
success All went well, and (usually) some data was returned. status data
fail There was a problem with the data submitted, or some pre-condition of the API call wasn’t satisfied. status, data  
error An error occurred in processing the request. status, code, message data

Examples

Empty success response

This indicates that the API call was successfully executed - no issues!

{
    "status": "success"
}
Success response with data

This indicates that the API call was successfully executed - and informational data is also returned. This example shows the result of segment creation - the segment that was created is returned.

{
    "status": "success",
    "data": {
        "id": "p7xw8xeI8f"
    }
}
Fail response with request body JSON structure validation results

When a problem occurs, you will receive a unique error code along with an explanational message highlighting the problem.

{
    "status": "fail",
    "data": {
        "errors": [
            {
                "code": "REQ002",
                "description": "Malformed request content - mandatory JSON element /biddingSettings/biddingStrategy is missing"
            },
            {
                "code": "REQ002",
                "description": "Malformed request content - mandatory JSON element /inventorySettings/inventoryType is missing"
            },
            {
                "code": "REQ003",
                "description": "Malformed request content - JSON element /inventorySettings/placementType is of incorrect type"
            },
            {
                "code": "REQ002",
                "description": "Malformed request content - mandatory JSON element /creatives(0)/facebook/title is missing"
            }
        ]
    }
}
Fail response with business logic validation results

When a problem occurs, wherever possible, the API will tell you exactly what went wrong so it can be corrected. In this example, an invalid placement type has been submitted - and the message explains the valid placement types that must be used.

{
    "status": "fail",
    "data": {
        "errors": [
            {
                "code": "E10024",
                "description": "url http://merchenta must be a valid URL prefixed http or https"
            },
            {
                "code": "E10005",
                "description": "placement type  must be ATF, BTF or UNKNOWN"
            },
            {
                "code": "EFB0001",
                "description": "For Facebook campaigns you must select all ATF,BTF,UNKNOWN placement targeting options anc BLIND inventory type"
            }
        ]
    }
}
Error response

If a major error is encountered, you’ll get details of the error code and an informational message.

{
    "status": "error",
    "message": "Authentication failed",
    "code": "AUTH002"
}

Response HTTP status codes

These codes are returned to indicate the overall status of the API call. Note that the API performs rate limiting, indicated by response code 429.

Code Short description Possible status types Description
200 OK success Standard response for successful HTTP requests. The actual response will depend on the request method and URL used.
400 Bad Request fail, error The request cannot be fulfilled due to bad syntax or data sent not passing business validation rules.
401 Unauthorized error Authentication is required and has failed or has not yet been provided.
403 Forbidden error The request was a valid request, but the server is refusing to respond to it.
429 Too Many Requests - The user has sent too many requests in a given amount of time.
500 Internal Server Error error A generic error message, given when an unexpected condition was encountered.

List of all error codes

Error code Error description
AUTH001 Authentication required - pass access token using ‘Authorization’ header
AUTH002 Authentication failed
AUTH003 Authorization failed
AUTH004 Maximum login attempts exceeded
COM0001 percentage must be in range of 0 to 100
E10001 Campaign codes can be a maximum of 32 characters long and may only contain characters A to Z, a to z, 0 to 9 and hyphen (“-“). Campaign codes must be prefixed with an advertiser code followed by hyphen (“-“).
E10002 domain name %s must be prefixed http or https
E10003 domain name %s is not valid
E10005 placement type %s must be ATF, BTF or UNKNOWN
E10006 inventory type %s must be BLIND or TRANSPARENT
E10007 when specifying a site list, you must select TRANSPARENT inventory
E10008 Currency code %s is invalid
E10009 Daily budget of %s %s must be >=$10 and <=$10000 or equivalent
E10010 please specify either a daily or a lifetime budget
E10011 campaign flight is for %1$s days – lifetime budget must be >=$(%1$s days * $10) and less than $10000 per day or equivalent
E10012 campaign start time %s must be in the future
E10013 please provide start time for campaign
E10014 campaign start time must be at least 24 hours before end time
E10015 campaign end time %s must be in the future
E10016 day must be given as: Monday, Tuesday, Wednesday, Thursday, Friday, Saturday or Sunday
E10017 campaign start time %s must be valid UNIX timestamp
E10018 campaign end time %s must be valid UNIX timestamp
E10019 campaign frequency cap %s must be between 4 and 500 ads per day
E10022 bidding algorithm must be valid for your account – try CPMCappedBiddingStrategy
E10023 pacing type must be ACCELERATED or PROPORTIONAL
E10024 url %s must be a valid URL prefixed http or https
E10025 max bids per second %s should be set between 1 and 1000
E10026 country code %s must be valid ISO country code
E10027 city %s is not valid
E10028 geo-targeting coordinates %s/%s must be valid latitude/longitude
E10029 geo-targeting radius must be between 10 miles and 500 miles
E10030 geo-targeting with zip codes requires countries to include ‘US’
E10031 geo-targeting with zip codes include one or more invalid codes specified
E10032 geo-targeting with DMA codes requires countries to include ‘US’
E10033 geo-targeting DMA codes include one or more invalid codes
E10041 contextual category code %s is not valid
E10042 segment with vendor code: %s id: %s is not valid
E10043 exchange block list contains an invalid exchange code: %s
E10044 optimisation strategy %s is not supported for this campaign - please use one of ROUND_ROBIN, WIN_RATE, CTR, ETR, CPM
E10045 state %s must be valid FIPS state codes
E10046 language targeting - language code %s should be in ISO 639-1 format
E10047 device targeting – please specify one or more of DESKTOP, SLATE, MOBILE, CONSOLE, WEARABLE, TV
E10048 device targeting includes unsupported OS %s
E10049 device targeting includes unsupported OS major version %s %s
E10050 device targeting includes unsupported OS minor version %s %s %s
E10051 device targeting includes unsupported device %s
E10052 device targeting includes unsupported browser %s
E10053 device targeting includes unsupported browser major version %s %s
E10054 device targeting includes unsupported browser minor version %s %s %s
E10055 first party audience segment rule ‘%s’ is not valid
E10056 first party audience segment rule ‘%s’ contains non existing segments: %s
E10058 creative dimensions %sx%s are not supported - valid dimensions are: 300x250, 728x90, 160x600, 120x600, 468x60, 320x50, 254x133, 336x280, 970x60, 300x600, 480x360, 640x360, 1920x800
E10058 media type %s must be either IMAGE, FLASH, FB_SIDEBAR, HTML-URL, HTML-SCRIPT
E10059 it is not possible to change status from %s to %s for creative %s
E10060 campaign code %s is invalid
E10061 creative code %s is invalid
E10062 incorrect campaign status %s - please specify one of PENDING, ACTIVE, INACTIVE, REJECTED, ARCHIVED
E10063 missing creative %s
E10064 new creative %s must have PENDING status
E10065 IntelliAd metadata is invalid or missing
E10066 incorrect expanding direction %s - please specify one of UP, DOWN, LEFT, RIGHT
E10067 incorrect expanding dimensions %sx%s - expandable creatives may not expand to more than twice the width or three times the height of the ad’s base dimensions
E10068 incorrect recommendation strategy %s - valid values are: BestSellerRecommenderStrategy, RecentlyViewedProductsRecommenderStrategy, HybridAffinityRecommenderStrategy, GeoProximityRecommenderStrategy, RandomRecommenderStrategy, RecentlyViewedRecommenderStrategy, ContentBasedRecommenderStrategy, TictailRecentlyViewedProductsRecommenderStrategy
E10069 no recommendation strategy defined - valid values are: BestSellerRecommenderStrategy, RecentlyViewedProductsRecommenderStrategy, HybridAffinityRecommenderStrategy, GeoProximityRecommenderStrategy, RandomRecommenderStrategy, RecentlyViewedRecommenderStrategy, ContentBasedRecommenderStrategy, TictailRecentlyViewedProductsRecommenderStrategy
E10070 Fallback clickthrough rate must be value between 0 and 1
E10071 incorrect realm %s - please specify one of VIEW, ADMIN, AGENCYADMIN
E10072 goal CPC must be between 0.2 and 10
E10073 goalType must be in either null or CPC
E10074 %s is not a valid video duration
E10075 Parameters videoDuration and videoBitrate and webmCreativeId can be specified only for VAST or VPAID creatives
E10076 Parameters videoDuration and videoBitrate and webmCreativeId are mandatory for VAST or VPAID creatives
E10077 Parameters vpaidJsLocation and vpaidJsParameters can be specified only for VPAID creatives
E10078 Parameters vpaidJsLocation and vpaidJsParameters are mandatory for VPAID creatives
E10101 Campaign must have at least one creative.
E10102 Creative codes can be a maximum of 32 characters long and may only contain characters A to Z, a to z, 0 to 9 and hyphen (“-“). Creative codes must be prefixed with a campaign code followed by hyphen (“-“).
E10113 campaign active window start time must be before end time
E10114 campaign active window days not given
E10201 commence optimisation after parameter needs to be an integer value between 10000 and 1000000
E10301 using lifetime budget requires campaign end date to be defined
E10401 Start retargeting after must be between 0 and 48 hours
E10402 Lookback window must be between 0 and 90 days
E10403 Please define either lookback window or first party audience segment rule
E10404 Start retargeting after can be used only in conjunction with lookback window
E10405 Unable to upload mobile id targeting
E10406 Unable to upload segment user ids targeting
E10501 please lock campaign %s before making changes - no lock
E10502 please lock campaign %s before making changes - lock expired
E10601 An exchange(s) you have selected for campaign does not permit sensitive content campaigns. For further details please edit your campaign accordingly or contact your Account Manager.
E10603 Clickthrough URLs must be at least 13 characters excluding transport prefix
EC30001 creative id %s does not exist
EC30002 creative id must not be empty
EC30003 third party creative id %s must be valid, fully qualified URL
EC30004 creative id %s not found in CDN
ECU1001 unable to upload ad creative. Please check it is multipart mime format and try again.
ECU1002 unable to upload ad creative from remote url %s. Please check if the URL is valid and try again.
ECU1003 creative contains invalid macro - %s
ECU1004 not supported file format - %s
EFB0001 For Facebook campaigns you must select all ATF,BTF,UNKNOWN placement targeting options anc BLIND inventory type
EFB0002 For Facebook campaigns you must have an audience segment rule defined OR retargeting enabled
EFB0003 Facebook restricts the use of geo-targeting on FBX – geo-targeting is not supported.
EFB0004 Creative dimensions for Facebook must be 254x133 segments. The recommended aspect ratio for images is 1.91:1.
EFB0101 Facebook title is required and must be a maximum of 25 characters including spaces, with no word having more than 20 characters.
EFB0102 Facebook title cannot start with punctuation.
EFB0103 Facebook title cannot contain duplicate consecutive punctuation characters with the exception of 3 ellipses…
EFB0104 Facebook title cannot contain double spaces.
EFB0105 Facebook title cannot contain more than 2 consecutive 1 character words.
EFB0106 Facebook title contains invalid macro
EFB0107 Facebook title cannot contain \ ^ ~ _ = { } [ ] | < >
EFB0108 Facebook title cannot contain International Phonetic Alphabet (IPA) Symbols
EFB0109 Facebook title cannot contain all capital letters
EFB0201 Facebook body is required and must be a maximum of 90 characters including spaces, with no word having more than 20 characters.
EFB0202 Facebook body cannot start with punctuation.
EFB0203 Facebook body cannot contain duplicate consecutive punctuation characters with the exception of 3 ellipses…
EFB0204 Facebook body cannot contain double spaces.
EFB0205 Facebook body cannot contain more than 2 consecutive 1 character words.
EFB0206 Facebook body contains invalid macro
EFB0207 Facebook body cannot contain \ ^ ~ _ = { } [ ] | < >
EFB0208 Facebook body cannot contain International Phonetic Alphabet (IPA) Symbols
EFB0209 Facebook body cannot contain all capital letters
EL10001 cannot lock campaign %s - is this the correct campaign code?
EL10002 cannot unlock campaign %s - is this the correct campaign code?
EP40001 segment name is empty or too short. Must be at least 2 characters long.
EP40002 segment name is empty or too long. Must not be longer than 50 characters
EP40003 unknown segment type %s. Valid types are: %s
EP40004 IntelliPixel path must be from 1 to 30 characters long.
EP40005 IntelliPixel path is not correct.
EP40006 IntelliPixel requires path pattern.
EP40007 Segment duration in days must be in range of 1 to 90.
EP40008 Incorrect segment status %s - please specify one of ACTIVE,INACTIVE
EP40009 Incorrect segment type %s - please specify one of EMAIL_OPEN,EMAIL_CLICK,VIEW,CART,PURCHASE,INTELLI_PIXEL,IDFA,ANDROID_ID
EP40010 Unable to update non-existing segment %s
EP40011 Unknown mobile identifier type %s
EP40012 IDFA or Android id should be MD5 encoded as hex string, its size must be 32 characters
EP40013 Internal error fetching segment
EP40014 Incorrect segment type %s - please specify one of EMAIL_OPEN,EMAIL_CLICK,VIEW,CART,PURCHASE,INTELLI_PIXEL,IDFA,ANDROID_ID
EP40015 Segment %s is not active
ER20003 Only historical dates are supported
ER20005 Fx rates for currency %s are not available for all dates between %s and %s - please try again with currency code USD
ER20006 Summary billing report is not available for today yet - please try again later.
ER20007 Start date must not be in the future
ER20008 End date must not be in the future
ER20009 Start date must be before end date OR start date and end date must be the same date
ER20010 Unknown event type %s
REQ001 Malformed request content
REQ002 Malformed request content - mandatory JSON element %s is missing
REQ003 Malformed request content - JSON element %s is of incorrect type
REQ004 Given date %s is not in yyyy-MM-dd format
REQ010 Malformed request content - missing param: %s
EADV001 incorrect advertiser status %s - please specify one of “ + AdvertiserStatus.values.mkString(“,”))
EADV002 no user with username %s
EADV003 username %s is invalid
EADV004 password required for user creation
EADV005 advertiser code %s too long - maximum 15 characters allowed
EADV006 advertiser code %s invalid
EADV007 advertiser CPM charge value: %s must be a positive number
EADV008 advertiser attribution windows must be between 0 and 90 days
EADV009 %s is not valid top private domain
EADV010 Blocklist does not contain this domain
SSP0001 Publisher ID already used
SSP0002 Publisher ID does not exist
PLNG001 Period must be between 0 and 90 days
PLNG002 Given date %s is not in yyyy-MM-dd format
UNKNOWN unknown error. (if you ever see this, be sure to ask Donald Rumsfeld about it before contacting support)
Next page  Previous page