Prescribed error messages for versioning errors?

For client development, it is preferred that clients don't do validation on requests and instead let the service validate and return any errors. The justification for this is that the client then doesn't prevent forward-compatibility if a service makes changes in a later version that weren't allowed in an earlier version.

One practical issue that this raises is that service error messages don't always tell the client user 1) what went wrong and 2) how to fix it. This is a particular problem for backward-compatible clients, when a service returns an error message that doesn't indicate that an operation/property wasn't supported in a given api-version.

There is an argument that could be made in favor of client-side validation in the case of version errors (i.e. a client could prevent a request to an endpoint that didn't exist in an early client version, which would not likely have forward-compatibility implications). However, this would be unnecessary if the Azure API Guidelines clearly prescribed the text of error messages services returned in the case of version-mismatches.

For example, if api-version=v1 query parameter was sent to an endpoint not introduced until api-version=v2, if the service message said something like "api-version=v1 not supported by this operation; operation was added in api-version=v2", this would indicate to the client user that they couldn't call this operation from a v2 client targeting api-version=v1 without the client needing to throw an exception to prevent it. It is less clear whether this would be desired for model property additions, as it would mean going back and changing api-version=v1 error messages when new properties were added in later api-versions. E.g. an error "invalid JSON" from a v1 service would later become "property Baz not supported on model Foo in api-version=v1; property was added in api-version=v2". This would prevent the need for client-side validation in this case.

Is this something the API Board would consider?

No file, test, or entry point is identified; start by reviewing the existing API Guidelines sections on versioning and service error responses, then read the issue discussion for the board's position. Done would require an agreed guideline change specifying whether and how version-mismatch messages should be prescribed.