API responses
Convertiser API uses conventional HTTP response codes to indicate the success or failure of an API request.
In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that failed given the information provided, and codes in the 5xx range indicate an error with API servers.
HTTP status code summary
| HTTP Code | Description |
|---|---|
| 200 - OK | Everything worked as expected. |
| 201 - Created | New resource record created successfully. |
| 204 - No Content | Resource action successfully processed. |
| 30x - Moved Permanently | Resource moved to another location, client should make another request. |
| 400 - Bad Request | The request was unacceptable, often due to missing a required parameter. |
| 401 - Unauthorized | No valid API key provided. |
| 404 - Not Found | The requested resource doesn't exist. |
| 409 - Conflict | The request conflicts with another request (perhaps due to using the same idempotent key, usually _version field). |
| 429 - Too Many Requests | Too many requests hit the API too quickly. We recommend an exponential backoff of your requests. |
| 50x - Server Errors | Something went wrong on API server backend. |
Response schema
All data is sent in JSON format.
Blank fields are included as null instead of being omitted.
All timestamps return in ISO 8601 format:
YYYY-MM-DDTHH:MM:SSZ
Representations
Summary Representations
When you fetch a list of resources, the response includes a subset of the attributes for that resource. This is the "summary" representation of the resource. (Some attributes are computationally expensive for the API to provide. For performance reasons, the summary representation excludes those attributes. To obtain those attributes, fetch the "detailed" representation.)
Example: When you get a list of websites, you get the summary representation of each website. Here, we fetch the list of websites:
GET /publisher/websites/
Detailed Representations
When you fetch an individual resource, the response typically includes all attributes for that resource. This is the "detailed" representation of the resource.
Example: When you get an individual website, you get the detailed representation of the website. Here, we fetch the website with defined ID:
GET /publisher/websites/websiteID/
The documentation provides an example response for each API method. The example response illustrates all attributes that are returned by that method.