docs(openapi): Document 404 related errors on acts and actor-builds endpoints (#2308)

## Summary

- Create reusable error response schemas
- Use granular 404 errors 
- Autogenerate 404 error response examples if possible

(Done only for `acts` and `actor-builds` endpoints to limit the scope of
the change. It should be done to all endpoints in follow-up PRs)

## Motivation

- Preparation for adding undocumented redispatch endpoints, which will
re-use the error schemas.
- Properly document different 404 errors returnable by the endpoint.
This will give the user a better idea about potential failures.

Example of granular 404s for an endpoint that relies on multiple
resources:

<img width="3500" height="972" alt="image"
src="https://github.com/user-attachments/assets/112757cb-183b-483e-8d15-34cfa14afda8"
/>

## Issues

Partially implements: #2286

<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> <sup>[Cursor Bugbot](https://cursor.com/dashboard?tab=bugbot) is
generating a summary for commit
f16d5e5. Configure
[here](https://cursor.com/dashboard?tab=bugbot).</sup>
<!-- /CURSOR_SUMMARY -->

Author: Pijukatel

apify-api/openapi/components/schemas/common/errors/ActorErrors.yaml

@@ -0,0 +1,77 @@
+ActorNotFoundError:
+  type: object
+  properties:
+    error:
+      type: object
+      properties:
+        type:
+          type: string
+          enum: [actor-not-found]
+        message:
+          type: string
+          example: Actor was not found
+
+ActorBuildNotFoundError:
+  type: object
+  properties:
+    error:
+      type: object
+      properties:
+        type:
+          type: string
+          enum: [record-not-found]
+        message:
+          type: string
+          example: Actor build was not found
+
+ActorRunNotFoundError:
+  type: object
+  properties:
+    error:
+      type: object
+      properties:
+        type:
+          type: string
+          enum: [record-not-found]
+        message:
+          type: string
+          example: Actor run was not found
+
+ActorRunTimeoutExceededError:
+  type: object
+  properties:
+    error:
+      type: object
+      properties:
+        type:
+          type: string
+          enum: [run-timeout-exceeded]
+        message:
+          type: string
+          example: Actor run exceeded the timeout of 300 seconds for this API endpoint
+
+ActorRunFailedError:
+  type: object
+  properties:
+    error:
+      type: object
+      properties:
+        type:
+          type: string
+          enum: [run-failed]
+        message:
+          type: string
+          example: "Actor run did not succeed (run ID: 55uatRrZib4xbZs, status: FAILED)"
+
+ActorVersionNotFoundError:
+  type: object
+  properties:
+    error:
+      type: object
+      properties:
+        type:
+          type: string
+          enum: [record-not-found]
+        message:
+          type: string
+          example: Actor version was not found

apify-api/openapi/components/schemas/common/errors/BuildErrors.yaml

@@ -0,0 +1,12 @@
+UnknownBuildTagError:
+  type: object
+  properties:
+    error:
+      type: object
+      properties:
+        type:
+          type: string
+          enum: [unknown-build-tag]
+        message:
+          type: string
+          example: 'Build with tag "latest" was not found. Has the Actor been built already?'

apify-api/openapi/components/schemas/common/errors/EnvVariableErrors.yaml

@@ -0,0 +1,12 @@
+EnvironmentVariableNotFoundError:
+  type: object
+  properties:
+    error:
+      type: object
+      properties:
+        type:
+          type: string
+          enum: [record-not-found]
+        message:
+          type: string
+          example: Environment variable was not found

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

@@ -53,7 +53,11 @@ get:
     "403":
       $ref: ../../components/responses/Forbidden.yaml
     "404":
-      $ref: ../../components/responses/NotFound.yaml
+      description: Not found - the requested resource was not found.
+      content:
+        application/json:
+          schema:
+            $ref: "../../components/schemas/common/errors/ActorErrors.yaml#/ActorBuildNotFoundError"
   deprecated: false
   x-legacy-doc-urls:
     - https://docs.apify.com/api/v2#/reference/actor-builds/build-object/get-build
@@ -95,7 +99,11 @@ delete:
     "401":
       $ref: ../../components/responses/Unauthorized.yaml
     "404":
-      $ref: ../../components/responses/NotFound.yaml
+      description: Not found - the requested resource was not found.
+      content:
+        application/json:
+          schema:
+            $ref: "../../components/schemas/common/errors/ActorErrors.yaml#/ActorBuildNotFoundError"
   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

@@ -33,6 +33,12 @@ post:
       $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"
   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

@@ -55,7 +55,11 @@ get:
     "400":
       $ref: ../../components/responses/BadRequest.yaml
     "404":
-      $ref: ../../components/responses/NotFound.yaml
+      description: Not found - the requested resource was not found.
+      content:
+        application/json:
+          schema:
+            $ref: "../../components/schemas/common/errors/ActorErrors.yaml#/ActorBuildNotFoundError"
   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

@@ -39,7 +39,11 @@ get:
     "400":
       $ref: ../../components/responses/BadRequest.yaml
     "404":
-      $ref: ../../components/responses/NotFound.yaml
+      description: Not found - the requested resource was not found.
+      content:
+        application/json:
+          schema:
+            $ref: "../../components/schemas/common/errors/ActorErrors.yaml#/ActorBuildNotFoundError"
   x-js-parent: BuildClient
   x-js-name: getOpenApiDefinition
   x-js-doc-url: https://docs.apify.com/api/client/js/reference/class/BuildClient#getOpenApiDefinition

apify-api/openapi/paths/actors/acts@{actorId}.yaml

@@ -83,6 +83,12 @@ get:
                   finishedAt: "2019-06-10T11:15:49.286Z"
     "400":
       $ref: ../../components/responses/BadRequest.yaml
+    "404":
+      description: Not found - the requested resource was not found.
+      content:
+        application/json:
+          schema:
+            $ref: "../../components/schemas/common/errors/ActorErrors.yaml#/ActorNotFoundError"
   deprecated: false
   x-legacy-doc-urls:
     - https://docs.apify.com/api/v2#/reference/actors/actor-object/get-actor
@@ -264,6 +270,12 @@ put:
                   finishedAt: "2019-06-10T11:15:49.286Z"
     "400":
       $ref: ../../components/responses/BadRequest.yaml
+    "404":
+      description: Not found - the requested resource was not found.
+      content:
+        application/json:
+          schema:
+            $ref: "../../components/schemas/common/errors/ActorErrors.yaml#/ActorNotFoundError"
   deprecated: false
   x-legacy-doc-urls:
     - https://docs.apify.com/api/v2#/reference/actors/actor-object/update-actor
@@ -302,6 +314,12 @@ delete:
           example: {}
     "400":
       $ref: ../../components/responses/BadRequest.yaml
+    "404":
+      description: Not found - the requested resource was not found.
+      content:
+        application/json:
+          schema:
+            $ref: "../../components/schemas/common/errors/ActorErrors.yaml#/ActorNotFoundError"
   deprecated: false
   x-legacy-doc-urls:
     - https://docs.apify.com/api/v2#/reference/actors/actor-object/delete-actor

apify-api/openapi/paths/actors/acts@{actorId}@builds.yaml

@@ -63,6 +63,12 @@ get:
             $ref: ../../components/schemas/actor-builds/ListOfBuildsResponse.yaml
     "400":
       $ref: ../../components/responses/BadRequest.yaml
+    "404":
+      description: Not found - the requested resource was not found.
+      content:
+        application/json:
+          schema:
+            $ref: "../../components/schemas/common/errors/ActorErrors.yaml#/ActorNotFoundError"
   deprecated: false
   x-legacy-doc-urls:
     - https://docs.apify.com/api/v2#/reference/actors/build-collection/get-list-of-builds
@@ -161,6 +167,12 @@ post:
             $ref: ../../components/schemas/actor-builds/BuildResponse.yaml
     "400":
       $ref: ../../components/responses/BadRequest.yaml
+    "404":
+      description: Not found - the requested resource was not found.
+      content:
+        application/json:
+          schema:
+            $ref: "../../components/schemas/common/errors/ActorErrors.yaml#/ActorNotFoundError"
   deprecated: false
   x-legacy-doc-urls:
     - https://docs.apify.com/api/v2#/reference/actors/build-collection/build-actor

apify-api/openapi/paths/actors/acts@{actorId}@builds@default.yaml

@@ -45,6 +45,19 @@ get:
             $ref: ../../components/schemas/actor-builds/BuildResponse.yaml
     "400":
       $ref: ../../components/responses/BadRequest.yaml
+    "404":
+      description: Not found - the requested resource was not found.
+      content:
+        application/json:
+          schema:
+            $ref: "../../components/schemas/common/errors/ActorErrors.yaml#/ActorNotFoundError"
+    "403":
+      # It should be 404, but is 403 for backwards compatibility. https://github.com/apify/apify-core/pull/17414
+      description: Not found - the requested resource was not found.
+      content:
+        application/json:
+          schema:
+            $ref: "../../components/schemas/common/errors/BuildErrors.yaml#/UnknownBuildTagError"
   x-js-parent: ActorClient
   x-js-name: defaultBuild
   x-js-doc-url: https://docs.apify.com/api/client/js/reference/class/ActorClient#defaultBuild