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:
| 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. |
Here are some error codes you might get and what they mean.
| Code | Description | Details |
|---|---|---|
| 400 | Client Error / Bad Request | The request was unacceptable. Probably due to incorrect formatting. |
| 403 | Forbidden/Unauthorized | The API key doesn't have permission to perform the request or there are no API 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 | The 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. |
| 429 | Rate Limit Exceeded | There 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-ResetYou can use the header X-RateLimit-Reset to know when you can make another request. |
Error Codes
| Error Code | Description |
|---|---|
| bad_request | The request could not be parsed. Please check the OpenAPI specification for the correct request schema. |
| empty_request | The request is empty. Please check the OpenAPI specification for the correct request schema. |
| internal_server_error | The 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_key | The API key in the authorization header is missing, invalid or expired. Please check the Authentication section for more details. |
| invalid_auction_id | The 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_type | The event type must be one of: "Impression", "Click", "Purchase". |
| invalid_promotion_type | One or more invalid promotion types in slots field. |
| invalid_session | The session object must contain a non empty sessionId value. See Session information for more details. |
| missing_aspect_ratio | Missing required aspect ratio for banner ads. |
| missing_auctions | You must specify at least one auction. |
| missing_context | Missing required context. Either a category, a list of products or a search query must be specified. |
| missing_placement | Missing required placement or placement.page field. |
| missing_product_id | Missing productId. |
| missing_promotion_type | An auction must request slots for at least one promotion type. |
| missing_purchased_at | Missing required purchasedAt field. |
| missing_session | Missing required session field. |
| missing_slots | Missing required slots field. |
| 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 | One of the purchase items had a quantity of less or equal than zero. |
| resolved_bid_id_not_found | The provided resolved bid ID does not match an internal record. |
| too_few_impressions | At lease one impression must be included. |
| too_few_slots | An auction must specify at least one slot. |
| too_many_auctions | At most 5 auctions can be run in parallel. If you need to increase the number please contact your KAM. |