The API was originally designed to mirror the behaviour of the existing StoryParser with minimal changes to the latter. Now that Open Doors are performing more semi-automated imports, the API needs better error-handling:
the StoryParser currently throws a generic Error when anything goes wrong: it should return different errors depending on what happened
similarly, the API relies on only a couple of HTTP status-inspired error codes and human-readable text messages to communicate errors - it should define a broader set of possible error codes and use the same ones for work and bookmark imports where appropriate
it should not use HTTP statuses to communicate information beyond simple success/failure
The purpose of all this will be to allow API clients to take action automatically based on the errors, without breaking existing behaviour for manual imports.
Testing will involve checking that manual imports are unchanged, and API testing will happen using a mass import temporary site.
ETA: In order to implement this without breaking existing Open Doors import sites (about half a dozen already lined up), I am taking this opportunity to roll over the API version to v2 to accommodate the improved error codes and messages.