The following page describes the errors you might get when calling Topsort's /auctions and /events endpoints or while using Topsort APIs. A very general classification of these is by their HTTP status code:

  • 4xx status codes mean a problem with the request sent to Topsort.
  • 5xx status codes indicates a problem with Topsort's service.
    Both error types return a JSON array of error objects. Each error object has these fields:
FieldTypeDescription
errCodestringA short string uniquely identifying the problem.
docUrlstringA link to this documentation providing more information about the error.
messagestringOptional. If present, human-readable explanation of or details about the error. The string for a given error may change over time; code should not parse or dispatch based on particular values for this field.

Here are some error codes you might get and what they mean.

Code DescriptionDetails
400Client Error / Bad RequestThe request was unacceptable. Probably due to incorrect formatting.
403Forbidden/UnauthorizedThe API key doesn't have permission to perform the request or there are no API tokens.
404Not FoundThe server cannot find the requested resource. Either the request URL is not on our routes, or the resource is not available (ie. the requested campaign does not exist)
422Unprocessable EntityThe body of the request doesn't correspond with the expected model. i.e, you are missing a property, or we were expecting a date and you sent a number. We also attach a useful error message to the response body.
429Rate Limit ExceededThere is an IP-based rate limit on central services. You'll receive this error when you reach the limit with the following headers added to the error response.
- X-RateLimit-Limit - total number of requests allowed for the time period
- X-RateLimit-Remaining - remaining number of requests for the time period
- X-RateLimit-Reset
You can use the header X-RateLimit-Reset to know when you can make another request.

Error Codes

Error CodeDescription
bad_requestThe request could not be parsed. Please check the OpenAPI specification for the correct request schema.
empty_requestThe request is empty. Please check the OpenAPI specification for the correct request schema.
internal_server_errorThe server has encountered a problem. This is an unexpected problem. Our team moves fast and usually fixes any cause for this error in a few hours.
invalid_api_keyThe API key in the authorization header is missing, invalid or expired. Please check the Authentication section for more details.
invalid_auction_idThe auction ID does not correspond to an auction. Please make sure that an auction ID returned by /auction is passed in the request.
invalid_event_typeThe event type must be one of: "Impression", "Click", "Purchase".
invalid_promotion_typeOne or more invalid promotion types in slots field.
invalid_sessionThe session object must contain a non empty sessionId value. See Session information for more details.
missing_aspect_ratioMissing required aspect ratio for banner ads.
missing_auctionsYou must specify at least one auction.
missing_contextMissing required context. Either a category, a list of products or a search query must be specified.
missing_placementMissing required placement or placement.page field.
missing_product_idMissing productId.
missing_promotion_typeAn auction must request slots for at least one promotion type.
missing_purchased_atMissing required purchasedAt field.
missing_sessionMissing required session field.
missing_slotsMissing required slots field.
no_productsAt least one product must be specified.
no_purchase_itemsAt least one item must be purchased.
purchase_item_quantity_less_or_equal_than_zeroOne of the purchase items had a quantity of less or equal than zero.
resolved_bid_id_not_foundThe provided resolved bid ID does not match an internal record.
too_few_impressionsAt lease one impression must be included.
too_few_slotsAn auction must specify at least one slot.
too_many_auctionsAt most 5 auctions can be run in parallel. If you need to increase the number please contact your KAM.