docs(openapi): Add generic 4xx errors to OpenAPI spec (#2328)

## Summary

- Add Agents directives about 4xx errors in the OpenAPI spec
- Add generic 4xx errors where suitable based on the directives.

## Motivation

- Solve OpenAPI validation errors for missing error responses

## Issues

Partially implements: #2286

Author: Pijukatel

AGENTS.md

@@ -55,13 +55,21 @@ Add code samples by creating files in `apify-api/openapi/code_samples/{javascrip
 
 - Prefer re-use of existing objects via `$ref` over duplication. Reusable components can be found in `/openapi/components`.
 - Components most suitable for re-use are:
-   - Request parameters and path parameters defined in  `/openapi/components/parameters`
-   - Request/response schemas defined in `/openapi/components/schemas`
-   - Explicit non-automatic examples defined in `/openapi/components/examples`
+  - Request parameters and path parameters defined in  `/openapi/components/parameters`
+  - Request/response schemas defined in `/openapi/components/schemas`
+  - Explicit non-automatic examples defined in `/openapi/components/examples`
 - When changing files in `/openapi/paths` look for opportunities to extract shared duplicate objects into re-usable components saved in `/openapi/components`.
 - When adding new endpoints, check first if any existing path is similar and if yes, try to re-use same components. If by adding new paths you create new duplication, try to extract it into a new components and reference it instead.
 - Prefer automatically generated examples from schema over explicit examples.
 
+#### Error responses
+- Re-use schemas for error responses defined in `/apify-api/openapi/components/responses`
+- Each endpoint should have at least following error responses: 400 (Bad Request), 405 (Method Not Allowed), 429 (Too Many Requests).
+- Endpoints that define `security: []` do not use any authentication.
+- Each endpoint that uses authentication should have at least following error responses: 401 (Unauthorized), 403 (Forbidden).
+- Each endpoint that has `runs/last` in its path or that has any ID related parameter (for example `actorId`, `buildId`, `runId`, `datasetId` and so on) should have at least one 404 (Not Found) error.
+- Each endpoint that has `requestBody` should have at least following error responses: 413 (Payload Too Large), 415 (Unsupported Media Type).
+
 ### Theme system
 
 Uses `@apify/docs-theme` package - a shared theme across all 6+ documentation repos. Don't modify theme files directly. Changes to the theme propagate via CI to all projects.

apify-api/openapi/components/responses/MethodNotAllowed.yaml

@@ -0,0 +1,9 @@
+description: Method not allowed.
+content:
+  application/json:
+    schema:
+      $ref: ../schemas/common/ErrorResponse.yaml
+    example:
+      error:
+        type: method-not-allowed
+        message: "This API end-point can only be accessed using the following HTTP methods: OPTIONS,GET"

apify-api/openapi/components/responses/PayloadTooLarge.yaml

@@ -0,0 +1,9 @@
+description: Payload too large - the request body exceeds the size limit.
+content:
+  application/json:
+    schema:
+      $ref: ../schemas/common/ErrorResponse.yaml
+    example:
+      error:
+        type: request-too-large
+        message: "The POST payload is too large (limit: 9437184 bytes, actual length: 10485760 bytes)."

apify-api/openapi/components/responses/TooManyRequests.yaml

@@ -0,0 +1,9 @@
+description: Too many requests - rate limit exceeded.
+content:
+  application/json:
+    schema:
+      $ref: ../schemas/common/ErrorResponse.yaml
+    example:
+      error:
+        type: rate-limit-exceeded
+        message: You have exceeded the rate limit. Please try again later.

apify-api/openapi/components/responses/UnsupportedMediaType.yaml

@@ -0,0 +1,9 @@
+description: Unsupported media type - the Content-Encoding of the request is not supported.
+content:
+  application/json:
+    schema:
+      $ref: ../schemas/common/ErrorResponse.yaml
+    example:
+      error:
+        type: unsupported-content-encoding
+        message: Content-Encoding "bla" is not supported.

apify-api/openapi/paths/actor-builds/actor-builds.yaml

@@ -32,6 +32,12 @@ get:
             $ref: ../../components/schemas/actor-builds/ListOfBuildsResponse.yaml
     "400":
       $ref: ../../components/responses/BadRequest.yaml
+    "401":
+      $ref: ../../components/responses/Unauthorized.yaml
     "403":
       $ref: ../../components/responses/Forbidden.yaml
+    "405":
+      $ref: ../../components/responses/MethodNotAllowed.yaml
+    "429":
+      $ref: ../../components/responses/TooManyRequests.yaml
   deprecated: false

apify-api/openapi/paths/actor-builds/actor-builds@{buildId}.yaml

@@ -38,6 +38,10 @@ get:
         application/json:
           schema:
             $ref: "../../components/schemas/common/errors/ActorErrors.yaml#/ActorBuildNotFoundError"
+    "405":
+      $ref: ../../components/responses/MethodNotAllowed.yaml
+    "429":
+      $ref: ../../components/responses/TooManyRequests.yaml
   deprecated: false
   x-legacy-doc-urls:
     - https://docs.apify.com/api/v2#/reference/actor-builds/build-object/get-build
@@ -71,12 +75,18 @@ delete:
       $ref: ../../components/responses/BadRequest.yaml
     "401":
       $ref: ../../components/responses/Unauthorized.yaml
+    "403":
+      $ref: ../../components/responses/Forbidden.yaml
     "404":
       description: Not found - the requested resource was not found.
       content:
         application/json:
           schema:
             $ref: "../../components/schemas/common/errors/ActorErrors.yaml#/ActorBuildNotFoundError"
+    "405":
+      $ref: ../../components/responses/MethodNotAllowed.yaml
+    "429":
+      $ref: ../../components/responses/TooManyRequests.yaml
   deprecated: false
   x-legacy-doc-urls:
     - https://docs.apify.com/api/v2#/reference/actor-builds/delete-build/delete-build

apify-api/openapi/paths/actor-builds/actor-builds@{buildId}@abort.yaml

@@ -32,6 +32,10 @@ post:
         application/json:
           schema:
             $ref: "../../components/schemas/common/errors/ActorErrors.yaml#/ActorBuildNotFoundError"
+    "405":
+      $ref: ../../components/responses/MethodNotAllowed.yaml
+    "429":
+      $ref: ../../components/responses/TooManyRequests.yaml
   deprecated: false
   x-legacy-doc-urls:
     - https://docs.apify.com/api/v2#/reference/actor-builds/abort-build/abort-build

apify-api/openapi/paths/actor-builds/actor-builds@{buildId}@log.yaml

@@ -27,12 +27,20 @@ get:
             2017-07-14T06:00:49.752Z Some useful debug information follows.
     "400":
       $ref: ../../components/responses/BadRequest.yaml
+    "401":
+      $ref: ../../components/responses/Unauthorized.yaml
+    "403":
+      $ref: ../../components/responses/Forbidden.yaml
     "404":
       description: Not found - the requested resource was not found.
       content:
         application/json:
           schema:
             $ref: "../../components/schemas/common/errors/ActorErrors.yaml#/ActorBuildNotFoundError"
+    "405":
+      $ref: ../../components/responses/MethodNotAllowed.yaml
+    "429":
+      $ref: ../../components/responses/TooManyRequests.yaml
   deprecated: false
   x-legacy-doc-urls:
     - https://docs.apify.com/api/v2#/reference/actor-builds/build-log/get-log

apify-api/openapi/paths/actor-builds/actor-builds@{buildId}@openapi.json.yaml

@@ -37,6 +37,10 @@ get:
         application/json:
           schema:
             $ref: "../../components/schemas/common/errors/ActorErrors.yaml#/ActorBuildNotFoundError"
+    "405":
+      $ref: ../../components/responses/MethodNotAllowed.yaml
+    "429":
+      $ref: ../../components/responses/TooManyRequests.yaml
   x-js-parent: BuildClient
   x-js-name: getOpenApiDefinition
   x-js-doc-url: https://docs.apify.com/api/client/js/reference/class/BuildClient#getOpenApiDefinition