All the REST services use a common XML Response message to deliver the results or statuses from a REST-call. Response message is sent both on success and error conditions: HTTP error messages are only sent if something is wrong in the HTTP protocol level. All application errors are reported via Response XML. The response comes always with HTTP response code '200 OK' and the client should investigate the actual code from <Status> and <StatusCode> elements for the real status of requested operation.
The format of the response (delivered in the BODY) is:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<Response version="1.0">
<Status></Status>
<StatusCode></StatusCode>
<FreeText language="ISO639-1 Languagecode"></FreeText>
<Content>
<Group>
<Value type="ValueType"></Value>
</Group>
</Content>
</Response>
The overall status of the response. The contents are either 'OK' or 'ERR'.
Four character alphanumeric representation of the status. The first character defines the system in Apix platform generating the message and the next is an internal function id, the last two characters are the actual error code.
| Systemcode | System name |
|---|---|
| 1 | Receiving |
| 2 | Sending |
| 3 | Conversion |
| 4 | Validation |
| 5 | Accounting |
| 6 | Archiving |
| 7 | Internal |
| 9 | Generic |
| Functioncode | Function name |
|---|---|
| ?One character function code | (only in internal documentation) |
| Statuscode | Meaning |
|---|---|
| 00 | OK |
| 01 | ERROR Data contents invalid |
| 02 | ERROR No available saldo |
| 03 | ERROR No signed contract for requested operation |
| 04 | ERROR Permission denied |
| 05 | ERROR No data available |
| 10 | WARNING Saldo negative (only on receiving) |
| 11 | ERROR Saldo is too low for receiving. All incoming messages are rejected (only on receiving) |
| 12 | ERROR request misformed |
| 99 | ERROR Internal error |
Note: It is recommended to show user also the StatusCode in error situations.
This is a freetext response intended for displaying to the user. The text is sent always in English, but additional elements in different languages maybe provided by the service.
Attribute 'language'
http://en.wikipedia.org/wiki/List_of_ISO_639-1_codes
Commonly used:
| Code | Language |
|---|---|
| en | English |
| fi | Finnish |
| se | Swedish |
This element contains additional information about the request intended for the client to refine.
Attribute 'type'
Defines the role and meaning of the element value.
Valid types:
Request
HTTP/1.1 200 OK
Content-Type: text/xml; charset=utf-8
Content-Length: 115Response
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<Response version="1.0">
<Status>ERR</Status>
<StatusCode>4701</StatusCode>
<FreeText language="en">Error: The invoice datafile fails validation. Reason: </FreeText>
<Content>
<Group>
<Value type="Saldo">180</Value>
<Value type="CostInCredits">0</Value>
</Group>
</Content>
</Response>