Incorrect typing of 429 responses

[danny-may]

All(?) endpoints are subject to ratelimiting, and so are able to return 429 responses. when a 429 response is sent, the json body of the response doesnt match the schema declared by the 4XX status in the current spec - the errors property will never be returned, and the global and retry_after properties are missing from the spec. The client generator im working on at the moment has to shim these definitions into the spec currently using the below structure.

On a related note, the ratelimit headers, which each endpoint returns, are also missing from the spec.

docs

{
  "paths": {
    "/blah": {
      "get|post|put|...": {
        "responses": {
          "429": {
            "$ref": "#/components/responses/RateLimitResponse"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "RateLimitError": {
        "type": "object",
        "description": "An error returned when you are rate limited",
        "properties": {
          "code": {
            "type": "integer",
            "description": "An error code for some limits"
          },
          "message": {
            "type": "string",
            "description": "A message saying you are being rate limited"
          },
          "retry_after": {
            "type": "number",
            "description": "The number of seconds to wait before submitting another request"
          },
          "global": {
            "type": "boolean",
            "description": "A value indicating if you are being globally rate limited or not"
          }
        },
        "required": [
          "message",
          "retry_after",
          "global"
        ]
      }
    },
    "responses": {
      "RateLimitResponse": {
        "description": "Rate limit error response",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/RateLimitError"
            }
          }
        }
      }
    }
  }
}

[yonilerner]

Thanks for reporting this