Updated API from documentation release

Author: ct-sdks[bot]

api-specs/history/api.raml

@@ -93,14 +93,30 @@ types: !include types/types.raml
 resourceTypes:
   base:
     get:
-      description: The `view_audit_log:{projectKey}` scope is required, and depending on the [resource type](ctp:history:type:ChangeHistoryResourceType) queried, their respective scopes must be granted.
+      description: |
+        The `view_audit_log:{projectKey}` scope is required, and depending on the [resource type](ctp:history:type:ChangeHistoryResourceType) queried, their respective scopes must be granted.
+
+        If the request exceeds the rate limit, a [TooManyRequests](ctp:history:type:TooManyRequestsError) error is returned.
       responses:
         200:
           body:
             application/json:
               type: RecordPagedQueryResponse
               example: !include examples/RecordPagedQueryResponse.json
           description: Records of the resource under query.
+          headers:
+            X-RateLimit-Limit:
+              description: |
+                Indicates the total number of tokens available when fully replenished.
+              type: string
+            X-RateLimit-Remaining:
+              description: |
+                Indicates the number of tokens available after the current query is completed.
+              type: string
+            X-RateLimit-Request-Cost:
+              description: |
+                Indicates the number of tokens used by the current query.
+              type: string
         400:
           body:
             application/json:
@@ -128,13 +144,24 @@ resourceTypes:
           description:
             Forbidden. Indicates that the authenticated client is not allowed to
             perform the request.
+        429:
+          body:
+            application/json:
+              type: ErrorResponse
+              example: !include examples/TooManyRequests.json
+          description: Too Many Requests. Indicates that the client has exceeded the API rate limit. Reduce the date range and resource types in your query to minimize the token usage, or retry the request after some time (indicated in the `Retry-After` header).
+          headers:
+            Retry-After:
+              description: |
+                The wait time, in seconds, before you can retry the request.
+              type: string
         500:
           body:
             application/json:
               type: ErrorResponse
               example: !include examples/InternalServerError.json
           description:
-            Internal Server Error. A 500 indicates that a request failed due to
+            Internal Server Error. A 500 indicates that the request failed due to
             a server-side problem that needs to be resolved before subsequent
             requests can succeed. It either indicates a temporary unavailability
             or permanent server-side problem that needs to be reported and

api-specs/history/examples/TooManyRequests.json

@@ -0,0 +1,10 @@
+{
+  "statusCode": 429,
+  "message": "You have made too many requests. Please try again later.",
+  "errors": [
+    {
+      "code": "TooManyRequests",
+      "message": "You have made too many requests. Please try again later."
+    }
+  ]
+}

api-specs/history/types/GraphQLError.raml

@@ -16,6 +16,5 @@ properties:
     items: any
     description: Query fields listed in order from the root of the query response up to the field in which the error occurred. `path` is displayed in the response only if an error is associated with a particular field in the query result.
   extensions:
-    type: object
-    #    type: GraphQLErrorObject
+    type: GraphQLErrorObject
     description: Dictionary with additional information where applicable.

api-specs/history/types/GraphQLErrorObject.raml

@@ -0,0 +1,15 @@
+#%RAML 1.0 DataType
+(package): Error
+type: object
+displayName: GraphQLErrorObject
+discriminator: code
+description: Represents a single error.
+properties:
+  code:
+    type: string
+    description: |
+      One of the error codes that is listed on the [Errors](/errors) page.
+  //:
+    type: any
+    description: |
+      Error-specific additional fields.

api-specs/history/types/GraphQLTooManyRequestsError.raml

@@ -0,0 +1,14 @@
+#%RAML 1.0 DataType
+(package): Error
+type: GraphQLErrorObject
+displayName: GraphQLTooManyRequestsError
+discriminatorValue: TooManyRequests
+description: |
+  Returned when the [Query Records](/../api/history/change-history#query-records) request exceeds the rate limit.
+
+
+
+  Reduce the date range and resource types in your query to minimize the token usage, or retry the request after some time (indicated in the `Retry-After` header).
+properties:
+  code:
+    type: string

api-specs/history/types/Record.raml

@@ -6,7 +6,7 @@ example: !include ../examples/Record.json
 description: |
   Captures the differences between the previous and next version of a resource.
 
-  The maximum number of Records that can be stored and their retention period are subject to a [limit](/../api/limits#records).
+  The maximum number of Records that can be stored and their retention period are subject to a [limit](/../api/limits#change-history).
 properties:
   version:
     type: integer

api-specs/history/types/TooManyRequestsError.raml

@@ -0,0 +1,18 @@
+#%RAML 1.0 DataType
+(package): Error
+type: ErrorObject
+displayName: TooManyRequestsError
+discriminatorValue: TooManyRequests
+description: |
+  Returned when the [Query Records](/../api/history/change-history#query-records) request exceeds the rate limit.
+
+  Reduce the date range and resource types in your query to minimize the token usage, or retry the request after some time (indicated in the `Retry-After` header).
+properties:
+  code:
+    type: string
+    description: |
+      `"TooManyRequests"`
+  message:
+    type: string
+    description: |
+      `"You have made too many requests. Please try again later."`

api-specs/history/types/types.raml

@@ -4,6 +4,7 @@ ChangeHistoryResourceType: !include ChangeHistoryResourceType.raml
 DateStringFilter: !include DateStringFilter.raml
 ErrorObject: !include ErrorObject.raml
 ErrorResponse: !include ErrorResponse.raml
+TooManyRequestsError: !include TooManyRequestsError.raml
 ModifiedBy: !include ModifiedBy.raml
 PlatformInitiatedChange: !include PlatformInitiatedChange.raml
 Source: !include Source.raml
@@ -17,8 +18,9 @@ GraphQLRequest: !include ../../api/types/graphql/GraphQLRequest.raml
 GraphQLResponse: !include ../../api/types/graphql/GraphQLResponse.raml
 GraphQLError: !include GraphQLError.raml
 GraphQLErrorLocation: !include ../../api/types/graphql/GraphQLErrorLocation.raml
+GraphQLTooManyRequestsError: !include GraphQLTooManyRequestsError.raml
 GraphQLVariablesMap: !include ../../api/types/graphql/GraphQLVariablesMap.raml
-# GraphQLErrorObject: !include ../../api/types/error/graphql/GraphQLErrorObject.raml
+GraphQLErrorObject: !include ../../api/types/error/graphql/GraphQLErrorObject.raml
 # Generated types
 AddAddressChange: !include change/AddAddressChange.raml
 AddAssetChange: !include change/AddAssetChange.raml