Errors and exceptions

Error information

Plumage provides two members that provide information about any error conditions detected during processing, ErrorCode and ErrorInfo.

ErrorCode is a short string containing a code indicating cause of error. It is intended to be interrogated by the invoking program. The ErrorCode string begins with either Fetch, CSV or Map, indicating whether the error occurred during the XML fetch stage (the getXMLData method), the CSV-generation stage (the getCSVData method), or the map-generation stage (the getTSDRData method). It may have the following values:

• Fetch-404: TSDR responded with HTTP code 404 (Not Found). This code means that the requested registration or serial number was not found on TSDR. Under normal conditions this code is returned when there is no such registration or serial number.
  Note: I have found that during some PTO TSDR outages (e.g., during the extended recovery from the December 2015 power outage), TSDR returned 404 (Not Found), rathert than the code 503 (Service Unavailable) that I would have expected. Therefore, do not rely on the Fetch-404 ErrorCode to definitively indicate that the requested registration or application does not exist.
• CSV-NoValidXML: The key-value pair generation step (getCSVData) was called but there was no valid XML to process.
• CSV-ShortCSV: Key-value pairs parse to fewer than two pairs; usually indicates faulty XSLT.
• CSV-InvalidKeyValuePair: An invalid key-value line was found in the CSVData; missing comma between the key and value.
• CSV-InvalidKey: An invalid key (non-alphanumeric) was found in the CSVData.
• CSV-InvalidValue: An invalid value (not quote-enclosed) was found in CSVData.
• CSV-UnknownError: An unknown error occurred generating CSVData.
• Map-NoValidCSV: The map generation step (getTSDRData) was called but there was no valid CSV data to process.

ErrorInfo is a longer string containing a human-readable description of the error. It provides text that can be displayed to a user or logged.

The only ErrorCode value occurring in ordinary use is Fetch-404, which may or may not indicate an error, depending on the caller's use case (i.e., it may be perfectly normal to check the PTO for a serial or registration number that is of a valid format but that does not exist). The other error codes should be encountered only if (a) you are calling the individual stages separately, and data expected by a stage is not in correct form; (b) have overridden the XSL (or if the PTO modifies the format of the data it provides) such that the XSLT transform used to parse the XML file does not function correctly; or (c) the USPTO is providing erroneous data due to a server-side error. Any other occurrence represents a bug in Plumage; please report it.

Exceptions

Plumage does not define or generate any user-specified exceptions. It will generate an appropriate system-defined exception under the following conditions:

• Requesting data from the PTO in an unsupported format (i.e., anything other than "ST66", "ST96" or "zip").
• Requesting data from the PTO for an unsupported record type (i.e., anything other than "r" indicating a registration number or an "s" indicating an application serial number).
• Requesting data from the PTO indicating an invalid value for the indicated type (i.e., anything other than a 7-digit number as a registration number or an 8-digit number for an application serial number).
• any condition resulting in any of the CSV-ShortCSV, CSV-InvalidKeyValuePair, CSV-InvalidKey, CSV-InvalidValue, or CSV-UnknownError error codes.

In each of these cases:

• Plumage-py raises a ValueError exception; and
• Plumage-dotnet throws System.ArgumentException.

Note that the error codes Fetch-404, CSV-NoValidXML, Map-NoValidCSV do not generate exceptions:

• Fetch-404 may be a normal condition, as described above.
• CSV-NoValidXML and Map-NoValidCSV conditions normally arise only if the stages are being called individually (i.e. not invoking getTSDRInfo, the usual way of using Plumage), which would ordinarily be done only if the programmer is altering the data between stages. These errors do not generate exceptions but instead respectively set CSVDataIsValid and TSDRDataIsValid to false, allowing other fields to be inspected and used if appropriate. Again, if you're using Plumage in the ordinary way, by calling getTSDRInfo, you should not see the CSV-NoValidXML and Map-NoValidCSV conditions.

Plumage does not trap and handle any errors or exceptions that occur in the course of execution, instead allowing such exceptions to propagate to the invoking program. For example, if a call fails due to the lack of an Internet connection or the unavailability of the PTO's TSDR system, or an error (other than 404) being returned by the PTO, the exception is reflected back to the calling program.

For example, if TSDR is down for maintenance (for example, if you were using the TSDR web site directly, you'd get the error "The system was unable to perform your search") and returns a 503 (Service Unavailable) error:

• Plumage-py will encounter a urllib2.HTTPError exception with a reason "Service Temporarily Unavailable".
• Plumage-dotnet will encounter a System.Net.WebException exception with a reason "The remote server returned an error: (503) Server Unavailable".

In either case, Plumage will not handle the exception. The calling program is expected to handle the exception or, if unable to handle, terminate. In short, for most errors encountered by factors external to Plumage, Plumage presents the error back to the caller.