docs(openapi): Autofix OpenAPI spec validation errors

[Pijukatel]

Summary

Autogenerated OpenAPI fixes suggestions based on validation errors generated from running API integration tests with OpenAPI validator turned on.

Error log: https://apify-pr-test-env-logs.s3.us-east-1.amazonaws.com/apify/apify-core/26794/api-b9787cbfc4c016266791e89ef8614c7d32e9175a.html

apify-core version: https://github.com/apify/apify-core/commit/57a2fbf9848fa2f64043cdb855a7b95c2a6caad6

Stop reason: Enough errors fixed in this iteration. The remaining response-validation errors fall under known false positives (nullable format: date-time fields), and the remaining request-validation errors are either intentional bad-input tests or out-of-scope (missing endpoints).

Detailed changes description

Error fixes

Allow insufficient-permissions on GET /v2/acts/{actorId}/builds/default 403

Files: apify-api/openapi/paths/actors/acts@{actorId}@builds@default.yaml:28-37
Error: WARN Response OpenAPI validation error {"url":"/v2/acts/{actorId}/builds/default","method":"GET","statusCode":403,"errors":[{"message":"must be equal to constant","errorCode":"const.openapi.validation","path":"/response/error/type"}]}
Root cause: The 403 response schema was hard-pinned to the const unknown-build-tag via UnknownBuildTagError, but the endpoint also returns 403 with type insufficient-permissions when an unauthenticated or non-owner caller requests a private Actor's default build (iamManager.ensureAccess throws errors.iam.insufficientPermissions). Switching the schema to the standard ErrorResponse (which references the ErrorType enum) covers both cases without losing the enum constraint.
Reference: https://github.com/apify/apify-core/tree/57a2fbf9848fa2f64043cdb855a7b95c2a6caad6/src/api/src/routes/actors/build_default.ts#L33

Add run-input-body-not-valid-json to ErrorType enum

Files: apify-api/openapi/components/schemas/common/ErrorType.yaml:301
Error: WARN Response OpenAPI validation error {"url":"/v2/schedules","method":"POST","statusCode":400,"errors":[{"message":"must be equal to one of the allowed values: 3d-secure-auth-failed, access-right-already-exists, action-not-foun...[truncated]","errorCode":"enum.openapi.validation","path":"/response/error/type"}]}
Root cause: When a Schedule is created with a non-JSON runInput.body, the API throws errors.scheduling.runInputBodyNotValidJson() with type run-input-body-not-valid-json, which was missing from the ErrorType enum.
Reference: https://github.com/apify/apify-core/tree/57a2fbf9848fa2f64043cdb855a7b95c2a6caad6/src/packages/errors/src/errors/scheduling.ts#L63

Add full-permission-actor-not-approved to ErrorType enum

Files: apify-api/openapi/components/schemas/common/ErrorType.yaml:129
Error: WARN Response OpenAPI validation error {"url":"/v2/acts/{actorId}/runs","method":"POST","statusCode":403,"errors":[{"message":"must be equal to one of the allowed values: 3d-secure-auth-failed, access-right-already-exists, action-not-foun...[truncated]","errorCode":"enum.openapi.validation","path":"/response/error/type"}]}
Root cause: Running a public full-permission Actor without prior approval throws errors.actor.fullPermissionActorNotApproved with type full-permission-actor-not-approved, which was missing from the ErrorType enum.
Reference: https://github.com/apify/apify-core/tree/57a2fbf9848fa2f64043cdb855a7b95c2a6caad6/src/packages/errors/src/errors/actor.ts#L58

Refactoring

None.

Issues

Partially implements: #2286

Unfixed errors

False positives

Nullable date-time fields trigger validator cascade on taggedBuilds, lastDispatch, schedule run timestamps, build finishedAt, and webhook dispatch calls[].startedAt/finishedAt

Error: WARN Response OpenAPI validation error {"url":"/v2/acts/{actorId}","method":"GET","statusCode":200,"errors":[{"message":"must be string,null","errorCode":"type.openapi.validation","path":"/response/data/taggedBuilds/latest/finishedAt"}, ...]} (and equivalents on /v2/webhooks/{id}, /v2/webhook-dispatches/{id}, /v2/actor-builds/{id}/abort, /v2/schedules, /v2/schedules/{id})
Root cause: The fields are correctly declared as type: [string, "null"] with format: date-time. The validator (express-openapi-validator/Ajv) does not honor multi-type definitions for formatted strings and reports must be string,null for valid null values. Per CLAUDE.md, this is a documented validator false positive. The cascading must match a schema in anyOf / must be null errors at the parent paths (taggedBuilds.latest, taggedBuilds, lastDispatch) are downstream effects of the same root cause: when the TaggedBuildInfo/ExampleWebhookDispatch branch fails on a (false) finishedAt mismatch, the validator then tries the null branch, which fails because the value is an object.
Reference: https://github.com/apify/apify-core/tree/57a2fbf9848fa2f64043cdb855a7b95c2a6caad6/src/api/src/lib/api_server.ts

Out of scope errors

Missing endpoints actor-tasks/{taskId}/runs/last/{abort,reboot,metamorph}

Error: WARN Request OpenAPI validation error {"url":"/v2/actor-tasks/{taskId}/runs/last/abort","method":"POST","errors":[{"message":"not found","path":"/actor-runs/{runId}/abort/"}]} (and reboot, metamorph variants, plus /v2/acts/{actorId}/runs/last/reboot)
Root cause: These endpoints exist in apify-core but are not yet defined in the OpenAPI spec. Per CLAUDE.md, adding new endpoints is out of scope for this autofix workflow.

Intentional malformed-input request validations

Error: Multiple WARN Request OpenAPI validation error lines for body/generalAccess enum/type, body must be object/oneOf on POST /v2/datasets/{id}/items, body/handledAt must match format date-time, headers/content-encoding enum, query/startedAfter/startedBefore must match format date-time, query/method/query/status Unknown query parameter, query/filter enum, OPTIONS method not allowed on /v2/users/test-user, XXX method not allowed on /v2/browser-info, unsupported media type application/x-www-form-urlencoded on POST /v2/acts, unsupported media type text/plain on POST /v2/tools/encode-and-sign, body must be array on DELETE /v2/request-queues/{id}/requests/batch, must have required property 'id'/'uniqueKey' on request-queue requests, body/eventTypes/0 enum on POST /v2/webhooks, body/options/timeoutSecs and body/input anyOf on actor-tasks POST/PUT, must have required property 'actId' on POST /v2/actor-tasks.
Root cause: All of these are followed by SFAIL log lines showing the API correctly rejects the malformed request. The integration tests deliberately send invalid input to verify error handling. Per CLAUDE.md, request-validation errors caused by intentional bad-input tests are not spec issues and must not be "fixed".

---

Generated by Claude Code

[apify-service-account]

Preview for this PR was built for commit c69420c and is ready at https://pr-2484.preview.docs.apify.com!