Error Handling

A Partner integration might have to deal with errors from time to time. The right approach and idempotency semantics to use for handling errors depend on the type of error being handled. Idempotency is defined as being able to apply the same operation multiple times without changing the result beyond the first try. Because a certain amount of intermittent failure is to be expected, Clients need a way of reconciling failed requests with a server and idempotency provides a mechanism for that.

The Platform API guarantees the idempotency of 'GET' and 'DELETE' requests, so it’s always safe to retry them when an error has been detected.

Content Errors

Content errors are the result of the contents of an API request being invalid and return a 4xx error code. Integrations should correct the original request, and try again.

Network Errors

Network errors are the result of connectivity problems between Client and Server and tend to manifest as low-level errors like socket or timeout exceptions. When intermittent problems occur, Clients are usually left in a state where they don't know or are not sure whether or not the server received the request. These events can be handled in a number of ways. For GET' or 'DELETE' requests it is safe to simply retry the request (e.g. you cannot delete the same User twice). For some 'POST' requests it is also safe to retry the request as the nature of the request itself will block duplicated events. For example, when registering a minor or adult with a unique email address because the PRIVO system does not allow duplicated email address's to be used accross multiple accounts. This same scenario may not necessarily hold true for child registrations. In some cases it will, like when a unique identifier is included in the request ( e.g. a unique Username). In other cases though, it may not. Partners can work with their PRIVO representative to determine what types of errors are possible in the integration to come up with a error handling plan that suites the integration.

Server Errors

Server errors are the result of a server-side problem and return a 5xx error code. These errors are the most difficult to handle, so we try to ensure that they happen as infrequently as possible. The result of a 5xx request should be treated as indeterminate. The most likely time to observe one is during a production incident and generally during such an incident's remediation. PRIVO engineers examine failed requests and try to appropriately reconcile the results of any mutations that resulted in server errors.

It is also possible for server errors to occur on the Client-side of the integration as well, for example during a webhook response. PRIVO attempts to identify all Client-side server errors using various types of system monitoring that has been put in place. When detected, PRIVO will attempt the request up to 3 times over the course of the proceeding minute. If the error does not resolve itself, then the monitoring system delivers a report of the error to the PRIVO engineering team. Such reports can be shared with Partner in an attempt to make aware the resulting issue and help Partner to remediate the problem.

Contact PRIVO:

    For error handling help, contact a PRIVO representative by sending an email to the PRIVO Support Team at support@privo.com.