Repository navigation
docs(openapi): Autofix OpenAPI spec validation errors - #2859
Merged
Merged
Conversation
Contributor
|
🗑️ Preview for this PR was deleted. |
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
force-pushed
the
claude/openapi-errors-fix-gb9atq
branch
from
August 27, 2026 06:05
86cb62d to
107c2be
Compare
Pijukatel
marked this pull request as ready for review
August 27, 2026 06:26
Pijukatel
requested review from
fnesveda,
janbuchar and
szaganek
as code owners
August 27, 2026 06:26
fnesveda
approved these changes
Aug 27, 2026
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*
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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-apiSOFT_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
publicConfigschemas 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
nullinActorNoticeenumapify-api/openapi/components/schemas/actors/ActorNotice.yaml:5-10{"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"}onGET /v2/storeand{"path":"/https/github.com/response/data/notice"}onGET /v2/actors/{actorId}- by far the largest group in both logs (~2093 item-level errors in iteration 1, 2322 in iteration 2)type: [string, "null"]but theenumlists only the three string values. In JSON Schema (OpenAPI 3.1)enumis exhaustive, so anullinstance fails validation unlessnullis itself an enum member. The API does returnnotice: null- the store pipeline storesnotice: actor.notice ?? null, the store item type isnotice: string | null, and the API's own test fixture shapes a response withnotice: null. The underlying representation inconsistency in apify-core is tracked in https://github.com/apify/apify-core/issues/29871.Drop
format: urifrom store itempictureUrlapify-api/openapi/components/schemas/store/StoreListActor.yaml:37-39{"errorCode":"format.openapi.validation","message":"must match format \"uri\"","path":"/https/github.com/response/data/items/{N}/pictureUrl"}onGET /v2/store(3 lines)Actor.pictureUrlis a free-form string in apify-core (type: String, max: 300, 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 3986uriformat. This also makesStoreListActor.pictureUrlconsistent withActor.yaml'spictureUrl, which declares noformat.Add
401response toGET /v2/users/{userId}apify-api/openapi/paths/users/users@{userId}.yaml:30-31{"message":"no schema defined for status code '401' in the openapi spec","path":"/https/github.com/v2/users/{userId}"}(statusCode 401, 1 line, username normalized to{userId})user-or-token-not-foundbefore the handler runs, so the operation can return 401 even though it is otherwise public. Compliant with RFC 9110 §15.5.2 (request "lacks valid authentication credentials"). Reuses the sharedUnauthorized.yamlresponse component.Add
cannot-publish-actor-taskto theErrorTypeenumapify-api/openapi/components/schemas/common/ErrorType.yaml:72{"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"}onPOST /v2/actor-tasksandPUT /v2/actor-tasks/{actorTaskId}, both status 400cannot-publish-actor-task, which the enum did not list. The log truncates the allowed-values list, so the missing member was identified by diffing everynewMeteorishErrorcode in apify-core against the enum:cannot-publish-actor-taskis the only absent code that is both status 400 and reachable from these endpoints, and an integration test asserts exactly this status and type.cannot-unpublish-actor-taskis also absent from the enum but is thrown only by the Console backend, never the public API, so it is deliberately not added.Add
409response toPUT /v2/schedules/{scheduleId}apify-api/openapi/paths/schedules/schedules@{scheduleId}.yaml:86-87{"message":"no schema defined for status code '409' in the openapi spec","path":"/https/github.com/v2/schedules/{scheduleId}"}(statusCode 409, 2 lines){userId, nameLowerCase};insertOrUpdateSchedulecatches the duplicate-key error and throwsschedule-name-not-uniquewith status 409, which the operation did not document. RFC 9110 §15.5.10 covers this case exactly,schedule-name-not-uniqueis already in theErrorTypeenum, andPOST /v2/schedulesalready documents 409 for the same condition -PUTwas the outlier. Reuses the sharedConflict.yamlresponse component.Issues
Partially implements: #2286