Errors

Any API call may fail, for a variety of reasons. When such a call fails, we return an error. We endeavour to provided meaningful error responses with the correct HTTP status code, status description, and a detailed Status Entity when an error is encountered.

Non XML Errors

In rare situations, we may not return an XML status entity (e.g. during system maintenance). In the event that the response is not valid XML, it is recommended to wait several minutes before retrying. If this occurs outside scheduled system maintenance, please let us know.

Warnings

Sometimes a call specifies something minor that cannot be completed, but the overall response can still succeed. This can result in a warning. Using warnings rather than errors was based on the Robustness Principle, which allows graceful degradation.

The Poppulo API issues warnings as headers (in all requests), and also as warning tags in Status Entities (in PUT, POST or DELETE requests). Common causes of warnings are unrecognised tags, failure to parse data types, references to unknown objects and some minor violations of business logic.

When developing your application, we strongly recommend you implement a zero-tolerance policy for warnings. Ideally, no calls should result in warnings. In production, you must choose between allowing warnings (graceful degradation) or treating them as errors. There are benefits and issues with either approach.

Logging

In either case, consider logging all warnings, and perhaps adding them to any error notification system. This will alert you in advance when operations are partially completed. Logging errors will greatly simplify things if you need to report a fault.