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

  • 4xx status codes mean there was 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.

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.