docs: rate limiting (#1878)

* docs: rate limiting

* fix: duplicated headers section

* fix: reword description

* fix: apply suggestions from code review to improve readability

Co-authored-by: Chris  <85164331+noon-dawg@users.noreply.github.com>

* fix: apply suggestions from code review to improve readability

Co-authored-by: Chris  <85164331+noon-dawg@users.noreply.github.com>

* refactor: add retry after header, materialize base problem

* fix: typo

---------

Co-authored-by: Chris <85164331+noon-dawg@users.noreply.github.com>

openapi/components/headers/X-RateLimit-Limit.yaml

@@ -0,0 +1,6 @@
+description: |-
+  Total number of rate limit tokens for this request within a rate limit period.
+  For more information, see [Rate limits](#section/Rate-limits).
+schema:
+  type: integer
+example: 3600

openapi/components/headers/X-RateLimit-Remaining.yaml

@@ -0,0 +1,6 @@
+description: |-
+  Remaining number of rate limit tokens for this request within the rate limit period. 
+  For example, in the sandbox environment, rate limits for non-GET endpoints are set at 3000 requests per 10 minutes.
+schema:
+  type: integer
+example: 3600

openapi/components/headers/X-RateLimit-Retry-After.yaml

@@ -0,0 +1,4 @@
+description: UTC timestamp after which the rate limit resets and the request can be retried.
+schema:
+  type: integer
+example: 1713187500

openapi/components/responses/TooManyRequests.yaml

@@ -0,0 +1,8 @@
+description: Request rate limit exceeded.
+headers:
+  X-RateLimit-Retry-After:
+    $ref: ../headers/X-RateLimit-Retry-After.yaml
+content:
+  application/json:
+    schema:
+      $ref: ../schemas/ProblemTypes/TooManyRequests.yaml

openapi/components/schemas/ProblemTypes/TooManyRequests.yaml

@@ -0,0 +1,34 @@
+type: object
+additionalProperties: true
+minProperties: 1
+description: RFC-7807 [problem details](https://tools.ietf.org/html/rfc7807) JSON object.
+properties:
+  type:
+    type: string
+    description: |-
+      Problem type in the form of a [URI](https://tools.ietf.org/html/rfc3986) reference.
+      It should provide human-readable documentation for the problem type.
+      When this member is not present, its value is assumed to be "about:blank".
+    format: uri
+    example: about:blank
+  title:
+    type: string
+    description: |-
+      Short, human-readable summary of the problem type.
+      Other than for the purposes of localization, this should not change from occurrence to occurrence of the problem.
+    example: Rate Limit Exceeded
+  status:
+    type: integer
+    description: HTTP status code.
+    minimum: 429
+    maximum: 429
+  detail:
+    type: string
+    description: Human-readable explanation that is specific to this occurrence of the problem.
+    example: A request cannot be executed because the user has sent too many requests within a certain period of time
+  instance:
+    type: string
+    description: |-
+      URI reference that identifies the specific occurrence of the problem.
+      It may or may not yield further information if dereferenced.
+

openapi/description.md

@@ -71,3 +71,12 @@ If you would like to implement a particular use case,
 
 To integrate Rebilly, and learn about related resources and concepts,
 see [Get started](https://www.rebilly.com/docs/dev-docs/get-started/).
+
+# Rate limits
+
+Rebilly enforces rate limits on the API to ensure that no single organization consumes too many resources.
+Rate limits are applied to the organization, and not to the API key.
+In sandbox environment, rate limits are enforced for non-GET endpoints and are set at 3000 requests per 10 minutes.
+You can find the exact number of consumed requests in the `X-RateLimit-Limit` and `X-RateLimit-Remaining` headers in the response.
+If the rate limit is exceeded, the API returns a `429 Too Many Requests` response
+and a `X-RateLimit-Retry-After` header that includes a UTC timestamp of when the rate limit resets.

openapi/paths/allowlists.yaml

@@ -47,16 +47,22 @@ post:
     description: Allowlist record.
     required: true
   responses:
-    201:
+    '201':
       description: Allowlist record created.
       headers:
         Location:
           $ref: ../components/headers/Location.yaml
+        X-RateLimit-Limit:
+          $ref: ../components/headers/X-RateLimit-Limit.yaml
+        X-RateLimit-Remaining:
+          $ref: ../components/headers/X-RateLimit-Remaining.yaml
       content:
         application/json:
           schema:
             $ref: ../components/schemas/Allowlist.yaml
-    401:
+    '401':
       $ref: ../components/responses/Unauthorized.yaml
-    409:
+    '409':
       $ref: ../components/responses/Conflict.yaml
+    '429':
+      $ref: ../components/responses/TooManyRequests.yaml

openapi/paths/allowlists@{id}.yaml

@@ -15,6 +15,11 @@ get:
   responses:
     '200':
       description: Allowlist record retrieved.
+      headers:
+        X-RateLimit-Limit:
+          $ref: ../components/headers/X-RateLimit-Limit.yaml
+        X-RateLimit-Remaining:
+          $ref: ../components/headers/X-RateLimit-Remaining.yaml
       content:
         application/json:
           schema:
@@ -35,3 +40,10 @@ delete:
   responses:
     '204':
       description: Allowlist record deleted.
+      headers:
+        X-RateLimit-Limit:
+          $ref: ../components/headers/X-RateLimit-Limit.yaml
+        X-RateLimit-Remaining:
+          $ref: ../components/headers/X-RateLimit-Remaining.yaml
+    '429':
+      $ref: ../components/responses/TooManyRequests.yaml

openapi/paths/aml-checks@{id}@review.yaml

@@ -22,6 +22,10 @@ post:
       headers:
         Location:
           $ref: ../components/headers/Location.yaml
+        X-RateLimit-Limit:
+          $ref: ../components/headers/X-RateLimit-Limit.yaml
+        X-RateLimit-Remaining:
+          $ref: ../components/headers/X-RateLimit-Remaining.yaml
       content:
         application/json:
           schema:
@@ -34,3 +38,5 @@ post:
       $ref: ../components/responses/NotFound.yaml
     '422':
       $ref: ../components/responses/ValidationError.yaml
+    '429':
+      $ref: ../components/responses/TooManyRequests.yaml

openapi/paths/aml-checks@{id}@start-review.yaml

@@ -19,6 +19,10 @@ post:
       headers:
         Location:
           $ref: ../components/headers/Location.yaml
+        X-RateLimit-Limit:
+          $ref: ../components/headers/X-RateLimit-Limit.yaml
+        X-RateLimit-Remaining:
+          $ref: ../components/headers/X-RateLimit-Remaining.yaml
       content:
         application/json:
           schema:
@@ -31,3 +35,5 @@ post:
       $ref: ../components/responses/NotFound.yaml
     '422':
       $ref: ../components/responses/ValidationError.yaml
+    '429':
+      $ref: ../components/responses/TooManyRequests.yaml

openapi/paths/aml-checks@{id}@stop-review.yaml

@@ -20,6 +20,10 @@ post:
       headers:
         Location:
           $ref: ../components/headers/Location.yaml
+        X-RateLimit-Limit:
+          $ref: ../components/headers/X-RateLimit-Limit.yaml
+        X-RateLimit-Remaining:
+          $ref: ../components/headers/X-RateLimit-Remaining.yaml
       content:
         application/json:
           schema:
@@ -32,3 +36,5 @@ post:
       $ref: ../components/responses/NotFound.yaml
     '422':
       $ref: ../components/responses/ValidationError.yaml
+    '429':
+      $ref: ../components/responses/TooManyRequests.yaml

openapi/paths/aml-settings.yaml

@@ -39,6 +39,11 @@ put:
   responses:
     '200':
       description: AML settings updated.
+      headers:
+        X-RateLimit-Limit:
+          $ref: ../components/headers/X-RateLimit-Limit.yaml
+        X-RateLimit-Remaining:
+          $ref: ../components/headers/X-RateLimit-Remaining.yaml
       content:
         application/json:
           schema:
@@ -48,6 +53,10 @@ put:
       headers:
         Location:
           $ref: ../components/headers/Location.yaml
+        X-RateLimit-Limit:
+          $ref: ../components/headers/X-RateLimit-Limit.yaml
+        X-RateLimit-Remaining:
+          $ref: ../components/headers/X-RateLimit-Remaining.yaml
       content:
         application/json:
           schema:
@@ -58,3 +67,5 @@ put:
       $ref: ../components/responses/Forbidden.yaml
     '404':
       $ref: ../components/responses/NotFound.yaml
+    '429':
+      $ref: ../components/responses/TooManyRequests.yaml

openapi/paths/api-keys.yaml

@@ -59,6 +59,10 @@ post:
       headers:
         Location:
           $ref: ../components/headers/Location.yaml
+        X-RateLimit-Limit:
+          $ref: ../components/headers/X-RateLimit-Limit.yaml
+        X-RateLimit-Remaining:
+          $ref: ../components/headers/X-RateLimit-Remaining.yaml
       content:
         application/json:
           schema:
@@ -69,6 +73,8 @@ post:
       $ref: ../components/responses/Forbidden.yaml
     '422':
       $ref: ../components/responses/ValidationError.yaml
+    '429':
+      $ref: ../components/responses/TooManyRequests.yaml
   x-codeSamples:
     - lang: PHP
       label: PHP-SDK-2.0

openapi/paths/api-keys@{id}.yaml

@@ -54,6 +54,10 @@ put:
       headers:
         Location:
           $ref: ../components/headers/Location.yaml
+        X-RateLimit-Limit:
+          $ref: ../components/headers/X-RateLimit-Limit.yaml
+        X-RateLimit-Remaining:
+          $ref: ../components/headers/X-RateLimit-Remaining.yaml
       content:
         application/json:
           schema:
@@ -66,6 +70,8 @@ put:
       $ref: ../components/responses/NotFound.yaml
     '422':
       $ref: ../components/responses/ValidationError.yaml
+    '429':
+      $ref: ../components/responses/TooManyRequests.yaml
   requestBody:
     $ref: ../components/requestBodies/ApiKey.yaml
   x-codeSamples:
@@ -91,6 +97,11 @@ delete:
   responses:
     '204':
       description: API key deleted.
+      headers:
+        X-RateLimit-Limit:
+          $ref: ../components/headers/X-RateLimit-Limit.yaml
+        X-RateLimit-Remaining:
+          $ref: ../components/headers/X-RateLimit-Remaining.yaml
     '401':
       $ref: ../components/responses/Unauthorized.yaml
     '403':
@@ -99,6 +110,8 @@ delete:
       $ref: ../components/responses/NotFound.yaml
     '409':
       $ref: ../components/responses/Conflict.yaml
+    '429':
+      $ref: ../components/responses/TooManyRequests.yaml
   x-codeSamples:
     - lang: PHP
       label: PHP-SDK-2.0

openapi/paths/application-instances@{applicationId}.yaml

@@ -58,6 +58,11 @@ put:
   responses:
     '200':
       description: Application instance updated.
+      headers:
+        X-RateLimit-Limit:
+          $ref: ../components/headers/X-RateLimit-Limit.yaml
+        X-RateLimit-Remaining:
+          $ref: ../components/headers/X-RateLimit-Remaining.yaml
       content:
         application/json:
           schema:
@@ -67,6 +72,10 @@ put:
       headers:
         Location:
           $ref: ../components/headers/Location.yaml
+        X-RateLimit-Limit:
+          $ref: ../components/headers/X-RateLimit-Limit.yaml
+        X-RateLimit-Remaining:
+          $ref: ../components/headers/X-RateLimit-Remaining.yaml
       content:
         application/json:
           schema:
@@ -77,6 +86,8 @@ put:
       $ref: ../components/responses/Forbidden.yaml
     '422':
       $ref: ../components/responses/ValidationError.yaml
+    '429':
+      $ref: ../components/responses/TooManyRequests.yaml
   x-codeSamples:
     - lang: PHP
       label: PHP-SDK-2.0
@@ -110,6 +121,8 @@ delete:
       $ref: ../components/responses/Forbidden.yaml
     '404':
       $ref: ../components/responses/NotFound.yaml
+    '429':
+      $ref: ../components/responses/TooManyRequests.yaml
   x-codeSamples:
     - lang: PHP
       label: PHP-SDK-2.0

openapi/paths/application-instances@{applicationId}@configuration.yaml

@@ -52,6 +52,11 @@ put:
   responses:
     '200':
       description: Application instance configuration updated.
+      headers:
+        X-RateLimit-Limit:
+          $ref: ../components/headers/X-RateLimit-Limit.yaml
+        X-RateLimit-Remaining:
+          $ref: ../components/headers/X-RateLimit-Remaining.yaml
       content:
         application/json:
           schema:
@@ -61,6 +66,10 @@ put:
       headers:
         Location:
           $ref: ../components/headers/Location.yaml
+        X-RateLimit-Limit:
+          $ref: ../components/headers/X-RateLimit-Limit.yaml
+        X-RateLimit-Remaining:
+          $ref: ../components/headers/X-RateLimit-Remaining.yaml
       content:
         application/json:
           schema:
@@ -71,3 +80,5 @@ put:
       $ref: ../components/responses/Forbidden.yaml
     '422':
       $ref: ../components/responses/ValidationError.yaml
+    '429':
+      $ref: ../components/responses/TooManyRequests.yaml

openapi/paths/applications.yaml

@@ -71,6 +71,10 @@ post:
       headers:
         Location:
           $ref: ../components/headers/Location.yaml
+        X-RateLimit-Limit:
+          $ref: ../components/headers/X-RateLimit-Limit.yaml
+        X-RateLimit-Remaining:
+          $ref: ../components/headers/X-RateLimit-Remaining.yaml
       content:
         application/json:
           schema:
@@ -83,6 +87,8 @@ post:
       $ref: ../components/responses/Conflict.yaml
     '422':
       $ref: ../components/responses/ValidationError.yaml
+    '429':
+      $ref: ../components/responses/TooManyRequests.yaml
   x-codeSamples:
     - lang: PHP
       label: PHP-SDK-2.0

openapi/paths/attachments.yaml

@@ -70,6 +70,10 @@ post:
       headers:
         Location:
           $ref: ../components/headers/Location.yaml
+        X-RateLimit-Limit:
+          $ref: ../components/headers/X-RateLimit-Limit.yaml
+        X-RateLimit-Remaining:
+          $ref: ../components/headers/X-RateLimit-Remaining.yaml
       content:
         application/json:
           schema:
@@ -82,6 +86,8 @@ post:
       $ref: ../components/responses/Conflict.yaml
     '422':
       $ref: ../components/responses/ValidationError.yaml
+    '429':
+      $ref: ../components/responses/TooManyRequests.yaml
   x-codeSamples:
     - lang: PHP
       label: PHP-SDK-2.0