Response codes and error handling

Most create and update operations require particular parameters. The API responds with an HTTP response code of 2xx when the operation is successful or an error code of 4xx, a text description of the error, and JSON content listing the incorrect or missing fields, along with the reason they were rejected. For example, if you POST an order without any parameters, the API responds with error code 400, and JSON in the response body indicating the required fields.

The following table describes the possible error types:

API error types

Error Description
Dependency Validation of the field failed due to restrictions based on the value of another field. The related field is specified in the field dictionary, and the field-specific error is detailed in the dependency dictionary.
Field Permission The current user does not have permission to modify the given field.
Not Unique

The field requires a unique value. For example, the value might need to be unique:

  • Across the entire instance

  • Within the object's parent account

  • Within the parent object

  • Within the object (in the case of an array field)

Object Not Found The object matching the given UID either does not exist, or was deleted.
Object One To One The object's parent must have exactly one child.
Object Type The object matching the given UID is not of the expected type.
Object Validation

Some of the input fields did not pass validation. Each field validation error includes:

  • Field definition in the field dictionary

  • Error type in type

  • A human-readable error in message

Each field validation error is detailed in the field_errors dictionary, where the keys are field names and the values are errors. When available, the object's UID is provided in uid.

Permission The current user does not have permission to perform the specified action on the specified object.
Range The input field value is either less than the minimum or greater than the maximum allowed value.
Read Only The field value may not be modified.
Reference Indicates that an object is referred to by another object and cannot be deleted. The referring objects are listed in referencing_objects.
Require The field requires a non-null value.
Size The input field value is too large or too small. For string fields, this is the allowed number of characters. For array fields, this is the allowed number of items in the array.

Too Many Requests

OpenX imposes an hourly API call rate limit on an instance for calls made both via script and normal usage within the Admin UI. If this hourly rate limit is exceeded, API calls will return the error code of "429 Too Many Requests". This error will be returned until the next hour starts and the API usage is reset.

Type The input field value is of the wrong type, and cannot be coerced into the correct type. For example, if a date/time field cannot parse a value into a native date, this error will be raised.
Unknown Field The input field does not exist for the object or sub-object.

One or more errors occurred within nested data structures. Sub-field validation errors are detailed in the error response under the following dictionaries:

  • field_errors dictionary. Error details for sub-object fields

  • item_errors dictionary. Error details for array fields

Value The allowable values for the field are constrained to a given set or must match a regular expression pattern. If the value must be one of a given set, the allowed values are specified in a request to the url in the field definition.

For information about HTTP status codes, see RFC 1945.