COUNTER API Exceptions: managing empty reports

This blog post from the CELUS team helps to outline common errors in Exception codes when harvesting ’empty’ COUNTER reports using the COUNTER API (sushi) protocol. COUNTER’s Exception codes were designed to allow report producers (publishers) to consistently report real or potential issues with report harvests to report consumers (libraries). When Exceptions are used incorrectly, it creates confusion and undermines the error reporting process.

The scale of the problem

The COUNTER API was designed for machines to use periodically and on a massive scale. Let’s consider a typical consortium with 50 members subscribing to 50 platforms, with a conservative two COUNTER reports per platform. This consortium would be harvesting 5000 individual reports each month. It is impractical if not impossible to manually inspect each harvested report when operating on this scale. It is therefore vital to report potential issues correctly and consistently, so that the harvesting tool (client) can handle the errors correctly and without human intervention.

In this post we describe the common Exception errors we have observed with empty reports (those with no usage data), and the problems they cause on the client side. We focus on machine harvesting in this post, but human users face the same problems.

An empty or blank report could mean many things:

• there was no usage for the requested time period
• it is too early to harvest the data for the requested time period (i.e. it hasn’t been processed yet)
• the data is more than two years old, and no longer available
• Or something else went wrong and the server simply could not return any data

Error type: missing Exceptions

One common issue with empty reports is that there is no Exception listed in the report header. Without an Exception code, the client has no way to know why the report is empty. No COUNTER report should be empty without an appropriate Exception:

• 3030 means no usage was found for the report (specifically, “No Usage Available for Requested Dates”)
• 3031 means data is not yet available (“Usage Not Ready for Requested Dates”)
• 3032 means data is no longer available (“Usage No Longer Available for Requested Dates”).

Where there is no Exception code, the client may decide to treat the response as meaning there is no usage. That means the client will miss data that appears later after usage has been processed for reporting. Alternatively, the client may decide to try harvesting later. That would cause unnecessary load on the server by repeatedly asking for empty reports.

Error type: 3030 as a catch-all

Another very common issue we see is that some report providers use the 3030 Exception code in situations where a more specific code should be used. If usage is not yet ready for the report period, 3031 should be used. If usage reports are no longer available for the report period, 3032 is the right code. While those three look very similar, and all explain that the empty report is to be expected, they have completely different meanings.

Exception 3031 means something like “You are asking us too early, we have not yet processed all our data; please come back later”. In contrast, 3030 could be translated as “The user account you are asking about did not record any usage with us”, and 3032 indicates “Sorry, but you are too late – we have already deleted the data for this time period”. Exceptions 3030 and 3032 indicate a permanent situation. Exception 3031 is temporary. If a client receives 3031 it should automatically try to harvest the report again again at a later point. If a client receives 3030 or 3032, the client should take no further action.

A report provider using 3030 when they should be using 3031 means the client won’t automatically try to harvest the report again. Librarians therefore have to know that the Exception is wrong, and that they have to manually call reports at a later date. If librarians aren’t aware of the incorrect Exception, they will under-value the report providers’ resources because they don’t have the full usage picture.

A similar situation can happen if report providers deliver 3030 instead of 3032. Report providers are only obliged to keep usage data available for the current year to date, plus two years of back data. This means calling 2022 data in 2025 could easily result in a 3032 Exception. If 3030 is delivered in place of 3032, it could create an impression that the resources were not used, rather than the true situation of a customer waiting too long to call their reports.

Error type: custom Exceptions

In some cases the problem of a missing 3030 is complicated when the report provider adds an extra, custom Exception. For example the provider may have added an extra metric not present in the Code of Practice. If a report is empty for any reason, one of 3030, 3031 or 3032 should be delivered. If the custom Exception is delivered instead, the client has to conclude that the custom Exception is the cause of the missing data. That triggers a manual review. This creates more work for the person harvesting the COUNTER reports through the client. It also potentially undermines trust in the accuracy of the report provider’s implementation of the standard.

Conclusion

Exceptions are an integral and important part of the COUNTER API. Not implementing them correctly can lead to confusion and unnecessary load on the client, the server, and the human users. Please, if you are a report provider, make sure that the cases described above do not apply to you!

If you have any questions, do not hesitate to ask us for help at ask@celus.net – we will be happy to help you to make your reports better and more reliable.