FAQ - Calais API

How do I ...?

Q: How can I create simple manual post?

A: See the code examples.

Q: How can I implement traffic compression?

A: See the detailed guidelines.

I'm Getting this error message ...

Q: I get error message from service - "couldn't finish process within given time limit". What does it mean?

A: Currently the text size limit is 100,000 chars, and any text longer than that will not be accepted. Large documents within this limit, however, might cause this error.

Q: When I submit XML content I get a document conversion error. What is causing this problem?

A: XMLs containing HTML-Entities, such as "&nbsp", "©", "é", "—", etc., are INVALID XMLs. You cannot include HTML entities in your XML, unless you declare them first, inside the DTD section of your XML. For instance, the following XML is invalid:

<MyText>
H&eacute;llo World &copy;
</MyText>


It becomes valid when you declare the entities, like this:

<!DOCTYPE test [
<!ENTITY copy "&#x00A9;">
<!ENTITY eacute "&#x00C9;">
]>
<MyText>
H&eacute;llo World &copy;
</MyText> 

Q: I am working with REST, using Python and get an error 403 message.

A: Take a look at this forum post for guidance.

Q: I get error message regarding root element of the Cparams XML I've sent. The XML is well formed, what could cause the problem?

A: This might be an URL-Encoding related issue. Always use URL-Encoding when using POST/GET. This is not necessary if you use a client-side SOAP layer (such as a .NET web reference or Axis in Java). 

Q: When trying to connect to Calais server, I get Proxy Authentication Error. What should I do?

A: Add proxy to your webClient, contact your system admin to get the proxy address and your credentials. See the code examples.

Q: I am using PHP SoapClient to invoke the Calais Web Service, but I get "Invalid request format" errors. What can cause this?

A: This might be the result of incorrect calls to the SoapClient's function. For example, the following is a non-valid call:

$result = $client->Enlighten($key, $text, $params);

It should be:

$enlighten_params = array(
'licenseID' => $key,
'content' => $text,
'paramsXML' => $params
);

I have a question ...

Q: Do I need to url-encode the post params?

A: Yes, always url-encode when using POST/GET. This is not necessary if you use a client-side SOAP layer (such as a .NET web reference or Axis in Java).

Q: I send a POST request, but I get suspiciously small response. What can cause this?

A: Make sure you have URL-Encoded the arguments; any non-coded ampersand sign would interfere with the request arguments.

Q: Can I invoke the Englighten web method in SOAP without using any client-side SOAP layer?

A: POST-ing to the SOAP url (".../enlighten/" or ".../enlighten/calais.asmx"): To use the SOAP url it is best if you have a client-side SOAP layer such as Axis in Java or .NET web reference. If you still choose to manually construct your SOAP envelope and POST, observe the following:

1. Use text/sml content type.
2. XML-escape your arguments (emphasis on paramsXML).
3. Make sure your content-length is accurate.
4. Make sure the resulting SOAP-envelope is a well-formed XML. 

Nevertheless, this practice is not recommended. It is better to use REST. (This information is also included in the API Calls documentation.)