Error management

Every API call can result in several error conditions.

In an HTTP protocol, the response statuses are identified by HTTP response status codes. All HTTP response status codes are separated into five categories.

The first digit of the status code defines the category of response. The last two digits are used to identify the status of the API call more specifically. There are five values for the first digit:

  • 1xx (Informational): The request was received, continuing process.
  • 2xx (Successful): The request was successfully received, understood, and accepted.
  • 3xx (Redirection): Further action needs to be taken in order to complete the request.
  • 4xx (Client Error): The request contains bad syntax or cannot be fulfilled.
  • 5xx (Server Error): The server failed to fulfill an apparently valid request.

This list shows how API Gateway connection points handle response codes:

  • 2xx status codes are considered successful. When such a status code is received, the data flow continues.
  • Status codes 401, 500, 503, and 504 are considered connection errors. When such a status code is received, the connection point retries sending the request.
  • All other status codes are considered document-specific configuration errors. When such a status code is received, the connection point generates a Confirm BOD.

Common errors when sending binary content

This table lists error messages that can occur when sending binary content such as images through an API Gateway connection point and how to resolve them:

Error message Likely cause Resolution
'Unrecognized image format; accepted formats: GIF, JPG, PNG' The target API received base64-encoded text instead of raw binary image data. This typically occurs when a BOD such as Sync.MyFile is used as the input document. BODs are XML-based and support text content only, so binary files are automatically base64-encoded. Change the input document type from a BOD to an ANY document. This preserves the native binary format. See the Binary content section.
'Please set an image parameter with image data for value' The target API did not receive any data for the file parameter, or the payload was not parsed correctly. Possible causes include an empty input document, an incorrectly configured form-data parameter, or the target system failing to parse a chunked transfer-encoded multipart request. Verify the form-data parameter configuration. Ensure that the Input Document option is selected for the file parameter and that the Content type is set correctly, for example, image/png. If an Enterprise Connector is in the path, test the call without it to determine whether chunked encoding is the cause.
'Image upload error' or similar format-related errors for files larger than 256 KB Large files sent through the Enterprise Connector may use chunked transfer encoding, which some target systems do not fully support for multipart request parsing. Test with and without the Enterprise Connector. If the call succeeds without the Enterprise Connector, the issue is related to how the target system processes chunked requests. Consult the target application vendor about chunked transfer encoding support.
HTTP 400 Bad Request with no descriptive error The multipart boundary may be malformed or missing its closing delimiter (--boundary--). This can occur in certain configurations that involve the Enterprise Connector and chunked transfer encoding. Enable debug logging for the IonApiCall and RestClient classes and review the raw HTTP payload. Verify that boundary strings are present at the start of each part and that the closing boundary delimiter is included at the end of the payload.