Link Search Menu Expand Document

PDF

Response Codes and Error Handling

Platform API


Most create and update operations require particular parameters. The API responds with the following:

  • An HTTP response code of 2xx when the operation is successful or an error code of 4xx.
  • A text description of the error.
  • 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.


API Error Types

The following table describes the possible API error types:

ErrorDescription
DependencyValidation 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 PermissionThe current user does not have permission to modify the given field.
Not UniqueThe 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 FoundThe object matching the given UID either does not exist, or was deleted.
Object One To OneThe object’s parent must have exactly one child.
Object TypeThe object matching the given UID is not of the expected type.
Object ValidationSome 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.
PermissionThe current user does not have permission to perform the specified action on the specified object.
RangeThe input field value is either less than the minimum or greater than the maximum allowed value.
Read OnlyThe field value may not be modified.
ReferenceIndicates that an object is referred to by another object and cannot be deleted. The referring objects are listed in referencing_objects.
RequireThe field requires a non-null value.
SizeThe 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 RequestsOpenX 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 return the error code of 429 Too Many Requests. This error is returned until the next hour starts and the API usage is reset.
TypeThe 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 is raised.
Unknown FieldThe input field does not exist for the object or sub-object.
ValidationOne 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
ValueThe 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.