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.
| Field | Type | Description |
|---|---|---|
| errCode | string | A short string uniquely identifying the problem. |
| docUrl | string | A link to this documentation providing more information about the error. |
| message | string | Optional. 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 | Description | Details |
|---|---|---|
| 400 | Bad Request | Unaccpetable request, i.e. Incorrect formatting |
| 403 | Forbidden/Unauthorized | API key issue or missing tokens |
| 404 | Not Found | The 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) |
| 422 | Unprocessable Entity | Mismatched request body and model, i.e, you are missing a property, or API is expecting a date but received a number |
| 429 | Rate Limit Exceeded | IP-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 Code | Description |
|---|---|
| bad_request | Request couldn't be parsed; check the OpenAPI specification for the correct schema. |
| empty_request | Request is empty; check the OpenAPI specification for the correct schema. |
| internal_server_error | Unexpected server problem; our team typically fixes these issues quickly. |
| invalid_api_key | Missing, invalid, or expired API key; see authentication for details. |
| invalid_auction_id | Auction ID doesn't correspond to an auction; ensure a valid auction ID is passed in the request. |
| invalid_event_type | Event type must be "Impression", "Click", or "Purchase". |
| invalid_promotion_type | Invalid promotion types in slots field. |
| invalid_session | session object must contain a non-empty sessionId; see auctions. |
| missing_aspect_ratio | Required aspect ratio for banner ads is missing. |
| missing_auctions | At least one auction must be specified. |
| missing_context | Required context missing; specify a category, product list, or search query. |
| missing_placement | Required placement or placement.page field is missing. |
| missing_product_id | productId missing. |
| missing_promotion_type | An auction must request slots for at least one promotion type. |
| missing_purchased_at | Required purchasedAt field missing. |
| missing_session | Required session field missing. |
| missing_slots | Required slots field missing. |
| no_products | At least one product must be specified. |
| no_purchase_items | At least one item must be purchased. |
| purchase_item_quantity_less_or_equal_than_zero | A purchase item has a quantity of less than or equal to zero. |
| resolved_bid_id_not_found | Provided resolved bid ID doesn't match an internal record. |
| too_few_impressions | At least one impression must be included. |
| too_few_slots | At least one slot must be specified in an auction. |
| too_many_auctions | Maximum of 5 auctions can run in parallel; contact your KAM to increase this limit. |