HTTP Responses
Unless otherwise specified in the documentation for the a given API endpoint, the following HTTP status codes are returned:
200 - Success
Unless otherwise specified, all API endpoints respond with a 200 for all successful requests. The body of the message depends on the API endpoint, and some endpoints have an empty body.
400 - Invalid Request
All API endpoints can return a 400 if the API request lacks required fields or is otherwise invalid. The response body is documented here.
This response type can also be returned if the security token in the path of an API request is malformed.
403 - Forbidden
If the system is configured to expire security tokens, API endpoints will return a 403 when an expired token is used. The body of the messages matches that of the 500 errors, with an message indicating when the token expired.
Clients should make a new call to the get-token endpoint to get a fresh security token after getting a 403 response.
404 - Not Found
The API or any intervening middleware may return a 404 when the URL does not route to an existing endpoint. For the purposes of this documentation, the body of such a 404 message is undefined, as there could be any number of intervening systems returning such an error, and not all such systems are under control of the Ad Server.
There may be API endpoints defined which return a 404 as an expected response when their underlying resource is not found, and those are documented in the respective page.
405 - Method not Allowed
All API endpoints will return a 405 when the request uses and HTTP method that the endpoint does not accept. This is most common when using a POST on an endpoint expecting a PUT and vice versa.
For the purposes of this documentation, the body of such a 405 message is undefined. Clients should encounter such an error during normal operation, as a 405 is typically indicative of a coding error that is easily detected.
500 - Internal Server Error
A 500 is returned when any other error occurs within the Ad Server. 500 errors are not typically the result of user error or bad input and instead are usually related to underlying system failures. Clients can retry the request if so desired.
For security purposes, no detailed error messages are included. HTTP 500 error bodies consist of a JSON object with a single field. error, with the following properties:
1 | |
| Field | Type | Description |
|---|---|---|
| message | string | For 500 responses, a boilerplate, generic message with no useful troubleshooting information. For other responses using this data type, additional information may be included. This field is assumed to be human-readable and not to be parsed by client code. |
| code | string | A string representation of the HTTP status code, such as "Forbidden" or "InternalServerError" |
| innerError | object | Always null for production deployments. May contain additional error information in testing deployments. |
| clientSessionId | string | The client-provided session id, if available. This can be used to correlate the error with server logs. See Custom HTTP Headers. Can be null or undefined |
| serverSessionId | string | The server-generated session id, if available. This can be used to correlate the error with server logs. Can be null or undefined |