Inconsistency in response when are limits are exceeded

[philipgough]

Perhaps it is my misunderstanding but I am finding it confusing the way rejections due to breach of rate limits are presented to the caller.

For example in a standard response where I have exceeded the limits, I would get something like this:

<?xml version="1.0" encoding="UTF-8"?>
<status>
  <authorized>false</authorized>
  <reason>usage limits are exceeded</reason>
  <plan>Basic</plan>
  <usage_reports>
    <usage_report metric="hits" period="minute">
      <period_start>2018-09-01 14:44:00 +0000</period_start>
      <period_end>2018-09-01 14:45:00 +0000</period_end>
      <max_value>1</max_value>
      <current_value>1</current_value>
    </usage_report>
  </usage_reports>
</status>

So we see there we have a human readable reason but we have not gotten an error code tag.

Now if I look at the docs here https://github.com/3scale/apisonator/blob/master/docs/rfcs/error_responses.md#currently-known-error_codes-and-proposed-classification I can see that limits_exceeded is a known error code that can be mapped to a 409 response, so that is slightly conflicting with the actual response.

What then causes further confusion is if I use the rejection_reason_header header is see that limits_exceeded is embedded in the response headers.

Personally, what I would like to see is the limits_exceeded as part of the xml in the error_code tag for consistency. I don't want to have to enable an extension for the single case where I need to know that I've exceeded limits, as per the docs linked above.