Skip to content

docs(openapi): Autofix OpenAPI spec validation errors - #2859

Merged
Pijukatel merged 6 commits into
masterfrom
claude/openapi-errors-fix-gb9atq
Aug 27, 2026
Merged

Pijukatel merged 6 commits into
masterfrom
claude/openapi-errors-fix-gb9atq

Conversation

@Pijukatel

@Pijukatel Pijukatel commented Aug 10, 2026 •

Copy link
Copy Markdown
Contributor

Summary

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

Error log: production API error logs (Mesmo, apify-api SOFT_FAIL entries) supplied as uploaded files - iteration 1: 0697c937-errors (Aug 3-9, 2026, 600 lines); iteration 2: 82f6eccd-errors (Aug 20-27, 2026, 599 lines). These are production logs with no public URL, so they are referenced by name for the lifetime of the PR.

apify-core version: iteration 1 https://github.com/apify/apify-core/commit/6a88dd05c766a3cf0ddbdab00730f539b77302b9, iteration 2 https://github.com/apify/apify-core/commit/59575e6d83b8c8f1046a49dd9d7365b0507ff67f

Stop reason: enough errors fixed - every unique error in both logs is either fixed here or documented below. The branch was rebased onto master before iteration 2, since the publicConfig schemas referenced by the second log landed in master after iteration 1. Each fix references the apify-core commit of its own iteration.

Detailed changes description

Error fixes

Allow null in ActorNotice enum

Drop format: uri from store item pictureUrl

Add 401 response to GET /v2/users/{userId}

Add cannot-publish-actor-task to the ErrorType enum

Add 409 response to PUT /v2/schedules/{scheduleId}

Issues

Partially implements: #2286

@github-actions github-actions Bot added this to the 147th sprint - Tooling team milestone Aug 10, 2026
@github-actions github-actions Bot added the t-tooling Issues with this label are in the ownership of the tooling team. label Aug 10, 2026
@apify-service-account

apify-service-account commented Aug 10, 2026 •

Copy link
Copy Markdown
Contributor

🗑️ Preview for this PR was deleted.

@Pijukatel Pijukatel added the adhoc Ad-hoc unplanned task added during the sprint. label Aug 10, 2026
claude added 5 commits August 27, 2026 06:00
Error: {"errorCode":"enum.openapi.validation","message":"must be equal to one of the allowed values: NONE, RESIDENTIAL_PROXY_REQUIRED, UNDER_MAINTENANCE","path":"/https/github.com/response/data/items/N/notice"} on GET /v2/store and {"path":"/https/github.com/response/data/notice"} on GET /v2/actors/{actorId}
Files: apify-api/openapi/components/schemas/actors/ActorNotice.yaml:5
Root cause: The schema declares type [string, "null"] but the enum lists only the three string values. In JSON Schema (OpenAPI 3.1) enum is exhaustive, so a null instance fails validation unless null is listed in the enum. The API returns notice: null for store items and actor objects - the store pipeline stores notice as "actor.notice ?? null" and the store item type is "notice: string | null".
Reference: https://github.com/apify/apify-core/tree/6a88dd05c766a3cf0ddbdab00730f539b77302b9/src/packages/actor-server/src/recombee/recombee_store_sync.ts#L555

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011mKWCZYL49Ay9Mzj2AeV2e
Error: {"errorCode":"format.openapi.validation","message":"must match format \"uri\"","path":"/https/github.com/response/data/items/N/pictureUrl"} on GET /v2/store
Files: apify-api/openapi/components/schemas/store/StoreListActor.yaml:37
Root cause: Actor.pictureUrl is a free-form string in apify-core (type String, max 300 chars, no URI validation), and the store search response rewrites it through the image proxy only when the value is truthy - an empty or malformed legacy value is passed through verbatim, so the response cannot guarantee RFC 3986 uri format.
Reference: https://github.com/apify/apify-core/tree/6a88dd05c766a3cf0ddbdab00730f539b77302b9/src/packages/actor/src/actors/actors.both.ts#L673

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011mKWCZYL49Ay9Mzj2AeV2e
Error: {"message":"no schema defined for status code '401' in the openapi spec","path":"/https/github.com/v2/users/{userId}"} on GET /v2/users/{userId} (statusCode 401)
Files: apify-api/openapi/paths/users/users@{userId}.yaml:30
Root cause: The endpoint requires no authentication, but the global authentication middleware validates any token that is provided. A request carrying an invalid token is rejected with 401 user-or-token-not-found before the handler runs, so the operation can return 401 even though it is otherwise public.
Reference: https://github.com/apify/apify-core/tree/6a88dd05c766a3cf0ddbdab00730f539b77302b9/src/api/src/middleware/authentication.ts#L95

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011mKWCZYL49Ay9Mzj2AeV2e
Error: {"errorCode":"enum.openapi.validation","message":"must be equal to one of the allowed values: 3d-secure-auth-failed, access-right-already-exists, action-not-foun...[truncated]","path":"/https/github.com/response/error/type"} on POST /v2/actor-tasks and PUT /v2/actor-tasks/{actorTaskId}, both status 400
Files: apify-api/openapi/components/schemas/common/ErrorType.yaml:72
Root cause: Failed task publication validation returns 400 with error type cannot-publish-actor-task, which the enum did not list. The log truncates the allowed-values list, so the missing member was identified by diffing every newMeteorishError code in apify-core against the enum: cannot-publish-actor-task is the only absent code that is both status 400 and reachable from these endpoints. An integration test asserts exactly this status and type. cannot-unpublish-actor-task is also absent but is thrown only by the Console backend, never the public API, so it is not added.
Reference: https://github.com/apify/apify-core/tree/59575e6d83b8c8f1046a49dd9d7365b0507ff67f/tests/integration/tests/actor_tasks/actor_tasks.publication.js#L370

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011mKWCZYL49Ay9Mzj2AeV2e
Error: {"message":"no schema defined for status code '409' in the openapi spec","path":"/https/github.com/v2/schedules/{scheduleId}"} (statusCode 409)
Files: apify-api/openapi/paths/schedules/schedules@{scheduleId}.yaml:86
Root cause: Renaming a schedule to a name another of the user's schedules already holds trips the unique index {userId, nameLowerCase}; insertOrUpdateSchedule catches the duplicate-key error and throws schedule-name-not-unique with status 409, which the operation did not document. RFC 9110 section 15.5.10 covers this case, schedule-name-not-unique is already in the ErrorType enum, and POST /v2/schedules already documents 409 for the same condition.
Reference: https://github.com/apify/apify-core/tree/59575e6d83b8c8f1046a49dd9d7365b0507ff67f/src/packages/actor-server/src/schedules.ts#L436

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011mKWCZYL49Ay9Mzj2AeV2e
@Pijukatel
Pijukatel force-pushed the claude/openapi-errors-fix-gb9atq branch from 86cb62d to 107c2be Compare August 27, 2026 06:05
@Pijukatel
Pijukatel marked this pull request as ready for review August 27, 2026 06:26
@Pijukatel
Pijukatel merged commit edda3dc into master Aug 27, 2026
15 checks passed
@Pijukatel
Pijukatel deleted the claude/openapi-errors-fix-gb9atq branch August 27, 2026 07:16
vdusek pushed a commit to apify/apify-client-python that referenced this pull request Aug 28, 2026
…ype (#1038)

Regenerates the Pydantic models, TypedDicts, and literal aliases from
the [published OpenAPI
specification](https://docs.apify.com/api/openapi.json)
(`v2-2026-08-24T085852Z` -> `v2-2026-08-27T071624Z`), picking up the
spec fixes from apify/apify-docs#2859.

- `StoreListActor.picture_url` is now `str | None` instead of `AnyUrl |
None`. The API doesn't guarantee an RFC 3986 URI here - legacy Actors
can carry an empty or malformed `pictureUrl` - so such Store items no
longer fail validation.
- `ErrorType` gains `cannot-publish-actor-task`, returned with 400 by
`POST /v2/actor-tasks` and `PUT /v2/actor-tasks/{actorTaskId}`.
- `ActorNotice` gains a `NONE_TYPE_NONE = None` member. The spec now
lists `null` in the enum (the API does return `notice: null`); since the
field is typed `ActorNotice | None`, `None` still validates to plain
`None`, so this is cosmetic.

*✍️ Drafted by Claude Code*
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

adhoc Ad-hoc unplanned task added during the sprint. t-tooling Issues with this label are in the ownership of the tooling team.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants