Type of error for the Document conversion
Fax API (3.0)
This document provides a detailed user guide and reference documentation on the Fax REST API.
If you have questions please contact us via our support portal and a team member will be happy to assist.
Note:
You must create an account on our support portal if you do not have one.
Sinch has a global server that will route your call to the appropriate geography region automatically:
https://fax.api.sinch.com/In general we retain fax logs and media for 13 months and you can access that via the API.
Find error codes and explanations here.
Overview
Languages
Servers
v3.0 of the Fax API
https://fax.api.sinch.com/v3/projects/{projectId}
The Fax API allows you to send and receive faxes. You can send faxes to a single recipient or to multiple recipients. You can also receive faxes and download them.
To send a TEST Outbound fax you can send a fax TO +19898989898. This will emulate all aspects of a real fax without charging your account.
OperationsWebhooks
Webhooks allow you to get updates in real-time about the status of your faxes. Webhooks are triggered by events such as the completion of a fax, and transmit information about the state of that fax to you via HTTP(S) or email. HTTP webhooks are multipart/form-data POST requests, and should be processed like form submissions.
Webhooks
The Emails endpoint allows you to configure the Fax to Email functionality. Fax to Email allows you to send an email and then receive a fax on your Sinch number or send a fax and have it sent to your email address. The service supports sending incoming faxes to multiple email addresses and having many numbers associated with one email address.
Operations
You can add cover pages to Sinch Fax either via the API or the Build dashboard.
A Fax service can have 0 or more cover pages configured.
Operations
When your receive a callback from the fax api notifying you of a failure, it will contain two values that can help you understand what went wrong: an errorCode and an type.
The type will give you a general idea of why the operation failed, whereas the errorCode describes the issue in more detail. Below we list the error_codes for the API, segmented by their corresponding error_type.
errorTypestring
| Value | Description |
|---|---|
| DOCUMENT_CONVERSION_ERROR | An error related to document conversion. |
Example: "DOCUMENT_CONVERSION_ERROR"
errorMessagestring
The error message
Example: "There was a problem in converting and merging files to the output file format. Contact support."
errorCodeinteger
The error code returned during document conversion.
| Enum Value | Description |
|---|---|
| 4 | There was a problem in converting and merging files to the output file format. Contact support. |
| 54 | Could not access the url you provided. {contentUrl} |
| 55 | The string_data URL you provided is invalid |
| 57 | There was a problem storing the file you provided. |
| 69 | There was a problem storing the file you provided. |
| 122 | User simulated Document Conversion Error |
| 128 | Could not determine mimetype for file. |
| 129 | Mimetype not supported. |
| 130 | Mimetype not supported: application/xml |
| 133 | Failed to normalize PDF document |
errorTypestring
Type of error for the Call
| Value | Description |
|---|---|
| CALL_ERROR | An error related to the call. |
Example: "CALL_ERROR"
errorMessagestring
A developer-facing error message
Example: "Busy"
errorCodeinteger
The error code returned describing the error of the call.
| Enum Value | Description |
|---|---|
| 11 | The call dropped prematurely |
| 15 | Congestion |
| 16 | Ring Timeout |
| 17 | Busy |
| 19 | Immediate Hangup |
| 30 | No answer from a fax machine. |
| 32 | Incompatible destination |
| 34 | Phone number not operational |
| 43 | Problem establishing connection |
| 49 | The destination phone number Is Not active |
errorTypestring
Type of error for the fax
| Value | Description |
|---|---|
| FAX_ERROR | An error related to the fax. |
Example: "FAX_ERROR"
errorMessagestring
A developer-facing error message
Example: "Could not establish a connection to the fax server."
errorCodeinteger
The error code returned describing the error of the call
| Enum Value | Description |
|---|---|
| 6 | There was an error communicating with the far side. |
| 7 | Far end cannot receive at the size of image |
| 8 | No response after sending a page |
| 10 | Disconnected after permitted retries |
| 12 | Received no response to DCS or TCF |
| 13 | Timed out waiting for the first message |
| 14 | Timed out waiting for initial communication |
| 18 | Unexpected message received |
| 20 | The HDLC carrier did not stop in a timely manner |
| 21 | Received a DCN from remote after sending a page |
Request errors are returned as HTTP status codes. The following table lists the possible error codes and their meaning.
The type will give you a general idea of why the operation failed, whereas the errorCode describes the issue in more detail. Below we list the error_codes for the API, segmented by their corresponding error_type.
{
"code": "404",
"error": "Bad Request",
"message": "
The request could not be understood by the server due to malformed syntax. The client SHOULD NOT repeat the request without modifications.
It could be invalid JSON, missing required fields, or other issues."
}{
"code": "402",
"error": "Payment required",
"message": "You have reached 0 balance on your account please make a payment."
}{
"code": "404",
"error": "Not found",
"message": "The resource is not found, not available, or does not exist."
}{
"code": "422",
"error": "Invalid parameters",
"message": "The request could not be understood by the server due to malformed syntax.
The client SHOULD NOT repeat the request without modifications."
details: {
fieldViolations: [
{
field: "to",
description: "The (+15551) is not a valid phone number"
}
]
}Rate limit exceeded, please back off and try again later. If you need higher rate please contact support.
Probably no body, but if there is a body it will look like this:
{
"code": "500",
"error": "Internal service error",
"message": "Most likely a temporary issue, please try again later. If the problem persists, please back of on this request and contact support."
}This non-http code will be used when there is an issue connecting to the designated callback URL. The response will look like this:
{
"error": "Could not connect to URL: https://123.456.789.00"
}Please note that the response code is probably the most important part of the response, but the error object will contain more information about the error. Not all errors return this object, and the details object is not always present.
A fax service identifies a set of configuration values. You can specify the service as a part of an API request or by associating a Sinch number with a service.
This can be useful if you want to point a group of numbers to a particular incoming fax URL, or want to set the storage strategy for some of your numbers but not all of them.
Operations