APIs allow you to specify the HTTP header X-Fieldpine-CallerHandling. This header can be used to indicate abilities of your requesting application such as the level of error handling available in your client application and also to request some special case handling that can be useful for development and debugging.

You can include multiple keywords in the header by seperating them with a comma or a space.

GET /OpenApi2/Some/Function HTTP/1.1
Host: example.com
User-Agent: Wizzo-Browser 14;
X-Fieldpine-CallerHandling: delay(300),drop-connection
X-Api-Key: your-Api-Key
Connection: keep-alive

Production Level Keywords

These keywords might be seen in production versions of your code

"X-Fieldpine-CallerHandling": "full"

Use this option where the sending system is fully able to handle all errors and retry operations after correcting errors. This is recommended during the development phase so as to not clog the POS with invalid attempts

"X-Fieldpine-CallerHandling": "audit"

This option is used when the sending system is capable of handling some errors and resending corrected data, but the POS should keep track of these and alert humans where possible as well the sending application. This is the default if no CallerHandling option is provided. An example might be an eCommerce website that is creating sales and has its own transmission queue. While the eCommerce site will have a report of failed sales, the POS will also maintain a list to ensure human notification as soon as possible

"X-Fieldpine-CallerHandling": "none"

Use this option if the sending application is unable to accept failure conditions. The error will still be returned to the calling application but it will also be stored for human review in the POS. An example might be sales being stored from an automatic vending machine.

"X-Fieldpine-CallerHandling": "queue"

When "queue" is used the server may immediately return a HTTP 202/Accepted response code and store the request data for later processing. You will not immediately receive error responses and need to either poll for the response or process a sale-load web hook. Queue mode provides the highest reliability of request delivery for clients as the server only needs to store the request and not attempt to process it immediately, this means any backend issues or high traffic conditions will not affect your API call.

With Queue mode it is explicitly permitted to queue the same request data multiple times.

"X-Fieldpine-CallerHandling": "akey:md5-of-key"

Caller holds a client side security key that can be identified with md5-of-key. When this is present the server may elect to return the results encrypted using this key. This encryption happens even over SSL connections. While SSL protects the data in flight over the network, these client side security keys provide an additional layer of client verification.

Use of this option is currently restricted to Fieldpine applications and is not available to web browser clients.

Production Level Keywords for Support

"X-Fieldpine-CallerHandling": "diag2(options)"

Instructs the application to request, log or return various internal diagnostics relating to the API Call. The following options are available

return

Causes the diagnositic data to be returned as a "diag" component in the response

For Example

GET /OpenApi/Something
X-Fieldpine-CallerHandling: diag2(return)

returns

{
  "data": {
    // Normal API response
  },
  "diag": {
    // diagnositic data
  }
}

Development Level Keywords

These keywords are intended for development and testing. Sending any of these keywords to a production server may be interpreted as development mode and the called API may elect to ignore the actual request. This means you should never place these directives in production code as an attempt to influence the server.

"X-Fieldpine-CallerHandling": "developer"

If set the API will attempt to perform extended checks and return every little detail that might be an issue.

"X-Fieldpine-CallerHandling": "readonly"

Requests that a read operation is performed and no actual database updates are applied. Only some APIs support this handling code, so check before use.

Readonly only means that we do not write or edit the primary purpose of the call. Sending a Sale Create with "readonly", will still cause API tracing to be recorded, and may write other audit records as well. Readonly is intended to be safe on a production server, but does not mean "invisible"

"X-Fieldpine-CallerHandling": "drop-connection"

Requests the server to hard disconnect the network link. This can be useful to verify that your app handles network failure during a call correctly.

"X-Fieldpine-CallerHandling": "delay(NNN)"

Asks the server to delay NNN seconds before processing the request. Servers will enforce a maximum delay of 1800 seconds. This can be useful for testing to verify your application can handle unexpected server delays.

Servers may elect not to honour this request, which may be done where a number of other requests are already being delayed artifically.