You should not insert new entries in the middle of enumerations?

[kendallb]

Ok, anyone who uses these API definitions to generate API code in strongly typed languages like C# or Java will end up with an enumeration for the 'error_code' field. We had a breakage yesterday when some of the carriers started returning new error values that were not defined in the spec so the resulting payload would fail to parse.

We reached out to support and the 'fix' is this commit:

https://github.com/ShipEngine/shipengine-openapi/commit/e3e74cb2acfe416300eb3aedee291b53cea66012

Which just adds the new errors to the enumeration. But that does not help anyone who has pre-compiled libraries as we all need to rebuild against the new spec. But worse, since you just inserted new values into the error table in the middle of the table, any existing binary values that represent those values when generated by an API will no longer be compatible.

Honestly it's just not a good idea to add new fields to enumerations as defined in the spec as you will break folks code running out in the wild.