Open2b version 7.8

Error handling

While using the API you may encounter errors that can be due to an error in your application such as "method does not exist", "missing parameter" or "parameter is not correct", or due to a temporary inability of the server to fulfill the request, for example "too many requests" or "internal system error".

In these cases the response sets the status field to "error" and the error field contains the reason for the error. For example:

  200 OK


{
  "status" : "error",
  "error" : {
    "field" : "name",
    "type" : "Malformed",
    "description" : "Name is not syntactically correct"
  }
}

Common errors

The following are errors that can occur in all calls and are due to your application. Typically these errors indicate that there is a bug in the application code that must be fixed, for example if the proper validations on parameter syntax were not performed before calling the method.

Field	Type	Description
unknown	UnknownField	Field '`<Field>`' is unknown
`<Field>`	AccessDenied	Access denied to field `<Field>`
`<Field>`	Missing	`<Field>` is required
`<Field>`	MissingCombination	`<Field>` is required if `<OtherField>` is provided
`<Field>`	Malformed	`<Field>` is not syntactically correct
`<Field>`	InvalidValue	`<Field>` is not a valid value
`<Field>`	InvalidCombination	`<Field>` is not allowed if `<OtherField>` is provided
`<Method>`	InvalidValue	`<Method>` is not available for this installation

Other errors

There are cases where the server receives the request but cannot process it, for example if the HTTP method is not POST, the key is not correct, the API method does not exist, or the maximum call limit has been reached (1000 every 5 minutes). In these situations the HTTP status will be different from 200 OK and the response will not be in JSON format. The following are the most common errors:

HTTP Status	Solution
403 Forbidden, malformed key	Use a valid key in the HTTP header "X-Key"
403 Forbidden, missing key	Add the HTTP header "X-Key" with the key
404 Not Found	Change the version number or method in the URL because it does not exist
405 Invalid Content-Length header	Fix the HTTP header "Content-Length" with a valid number
405 Invalid Content-Type header	Use one of "application/json" and "text/javascript" for the HTTP header "Content-Type"
405 Method Not Allowed	Use the HTTP POST method
405 Missing Content-Length header	Add the HTTP header "Content-Length"
405 Missing Content-Type header	Add the HTTP header "Content-Type"
400 Bad Request, malformed JSON data	Fix the request body so it is JSON
503 Service Unavailable	Wait the number of seconds indicated in the response HTTP header "X-Wait-Seconds"

There can also be cases where the server does not receive the request or your application does not receive the response, for example due to network errors. In this case the HTTP status will be different from 200 OK and the response will not be in JSON format.

Also consider errors that can be generated by the libraries used by your application to send HTTP requests, such as "socket error" or "domain does not exist".

Do not follow 3xx redirects

When making an HTTP call to the APIs, you should never follow redirects. A response with HTTP status 3xx (300, 301, 302, 303, 307) can mean the URL in the call is incorrect or the server is not configured correctly. Consult the documentation of the library you are using to perform HTTP calls to learn how to prevent the library from automatically following redirects.