Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: Migrated to Confluence 5.3

Generic Response Message

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:

Code Block
xml
xml
<?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>

Status (repeats ONCE)

The overall status of the response. The contents are either 'OK' or 'ERR'.

StatusCode (repeats ONCE)

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.

FreeText (Repeats 1..n)

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

sv

Swedish

Value (Repeats 0..n)

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:

?Appendix- LIST Value types

Examples

Code Block
xml
xml
HTTP/1.1 200 OK
Content-Type: text/xml; charset=utf-8
Content-Length: 115

<?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>