Every client of a SOAP API must handle several kinds of errors/issues, which can be classified as:
- Authentication errors (usually related to OAuth 2.0 token expiration/invalidation).
- Network errors (connection errors, SSL certification validation errors, timeouts, too many calls errors).
- XML/UTF-8 encoding (not every UTF-8 valid sequence is a valid XML sequence; for instance: some character controls are not allowed inside XML documents).
- Errors reported from the server (in this case, ServiceNotAvailableException and AuthenticationFailedException).
- Client-side specific errors (errors reported from the client-side technology, such as PHP SOAP Client, Java JAX-WS client, .NET client).
Handling ServiceNotAvailableException errors
Every operation in this SOAP API can result in a SOAP fault named ServiceNotAvailableException. This kind of response contains a 'message' property with a JSON-formatted description of the error.
Here is an example:
{
"errorType":"invalid_value",
"parameterName":"idContact",
"value":"xxxx",
"debugMessage","value xxxx is not a valid idContact"
}
Every error response will contain at least the "errorType" field, which can hold the following values:
| Value | Description |
|---|---|
| invalid_value | The value supplied is not valid; for instance: the system was expecting a number but the value is not castable to a number or the entity referrer by the request does not exist |
| api_rate_limits | The API rate limits have been exceeded for the specified "timeframe" |
| permissions_error | The user who is issuing the request does not have the permission to access the requested resource |
| importer_errors | Special category or error operation which import HTML content, usually the JSON response will contain more detailed information |
| internal_error | The system encountered an internal error, the error will be automatically submitted to the platform monitoring service, the application can retry the request once |
| not_implemented | The operation is trying to access a feature/resource which is not available on the account |
| unknown_error | The system encountered an internal error, the error will be automatically submitted to the platform monitoring service |
Please note that in case of network errors, client-side errors or XML/UTF-8 errors, this kind of response will not be available on the client side.
The field "debugMessage" is intended only as a further information useful for debugging purposes. These messages are very likely subject to changes from version to version of the platform.
Note
The system performs extensive auditing in order to detect inappropriate use of this API.
In order to avoid compromising the operation of your account, the system blocks calls identified as possible abuses (for example, when too many individual WS calls per hour or day are detected, for which it would be advisable to use batch calls).
If you encounter this problem, please contact our help desk for further details.
The system performs extensive auditing in order to detect inappropriate use of this API.
In order to avoid compromising the operation of your account, the system blocks calls identified as possible abuses (for example, when too many individual WS calls per hour or day are detected, for which it would be advisable to use batch calls).
If you encounter this problem, please contact our help desk for further details.