Response

When a request is successful, a response body will typically be sent back in the form of a JSON object or an array of JSON objects.  Every endpoint description on this site includes an example response and explanation of all possible response parameters.

Offective maintains the following response policies:

For every request:

  • HTTP status 401 including an errorMessage JSON object will be returned if authentication fails or ratelimit is exceeded. More information about error messages below.
  • HTTP status 400 including an errorMessage JSON object will be returned if the request was not processed correctly due to for example an error in submitted data or validation errors.
  • HTTP status 500 including an errorMessage JSON object will be returned if a technical error has occurred.

For PUT and POST requests:

  • HTTP status 200 with an empty JSON object will be returned if the object was not updated or created.
  • HTTP status 400 will probably occur instead, which will contain detailed information as to why the request did not succeed.
  • HTTP status 200 with an JSON representation of the update or newly created object will be returned if the request succeeded.

For GET requests:

  • HTTP status 200 with an empty JSON response with will be returned if no objects are found.
  • HTTP status 200 with an JSON array of items will be returned if there are objects found.

In general, when an error occurs, the response will contain JSON information about the error. A typical JSON error message will look like this:

Most common errors are:

  • HTTP 401, UNAUTHORIZED: Ratelimit exceeded
    You have exceeded the maximum requests for the past hour.
  • HTTP 401, UNAUTHORIZED: Invalid authentication credentials
    Your API key or username is incorrect or the combination of both is incorrect.
  • HTTP 400, INVALID_JSON: JSON is incorrect
    You have requested with invalid JSON data. The details are usually in the ‘errorMessage’
  • HTTP 405, METHOD_NOT_ALLOWED: Invalid HTTP method
    The request method is invalid or incompatible with the destination endpoint. 
  • HTTP 500, SYSTEMERROR: An system error has occured within Offective
    If your call generates an technical error within Offective, this error will be returned.