This page outlines errors encountered when using Topsort's /auctions and /events endpoints or APIs, classified by HTTP status code:

4xx: Request problem
5xx: Topsort service problem

Both errors return JSON arrays containing error objects with fields: errCode, docUrl, and an optional message.

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 and Meanings:

429: Rate Limit Exceeded - IP-based rate limit reached

Code DescriptionDetails
400Bad RequestUnaccpetable request, i.e. Incorrect formatting
403Forbidden/UnauthorizedAPI key issue or missing 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 EntityMismatched request body and model, i.e, you are missing a property, or API is expecting a date but received a number
429Rate Limit ExceededIP-based rate limit reached. This error comes with following headers:
- 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- when you can make another request

Error Codes

Error CodeDescription
bad_requestRequest couldn't be parsed; check the OpenAPI specification for the correct schema.
empty_requestRequest is empty; check the OpenAPI specification for the correct schema.
internal_server_errorUnexpected server problem; our team typically fixes these issues quickly.
invalid_api_keyMissing, invalid, or expired API key; see authentication for details.
invalid_auction_idAuction ID doesn't correspond to an auction; ensure a valid auction ID is passed in the request.
invalid_event_typeEvent type must be "Impression", "Click", or "Purchase".
invalid_promotion_typeInvalid promotion types in slots field.
invalid_sessionsession object must contain a non-empty sessionId; see auctions.
missing_aspect_ratioRequired aspect ratio for banner ads is missing.
missing_auctionsAt least one auction must be specified.
missing_contextRequired context missing; specify a category, product list, or search query.
missing_placementRequired placement or field is missing.
missing_product_idproductId missing.
missing_promotion_typeAn auction must request slots for at least one promotion type.
missing_purchased_atRequired purchasedAt field missing.
missing_sessionRequired session field missing.
missing_slotsRequired slots field missing.
no_productsAt least one product must be specified.
no_purchase_itemsAt least one item must be purchased.
purchase_item_quantity_less_or_equal_than_zeroA purchase item has a quantity of less than or equal to zero.
resolved_bid_id_not_foundProvided resolved bid ID doesn't match an internal record.
too_few_impressionsAt least one impression must be included.
too_few_slotsAt least one slot must be specified in an auction.
too_many_auctionsMaximum of 5 auctions can run in parallel; contact your KAM to increase this limit.