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-Reset You 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. |