Why valid OpenAPI fails AWS API Gateway import

An OpenAPI validator can accept your file while AWS API Gateway rejects its import or ignores part of its meaning. OpenAPI validity, the gateway’s supported subset, and a working AWS integration are separate checks.

If you see BadRequestException or Errors found during import, start with the detailed message. Neither phrase, by itself, identifies the broken field.

Check selected REST import issues locally →

First, confirm REST API or HTTP API

This guide and checker target API Gateway REST APIs with OpenAPI 3.0. AWS also accepts OpenAPI 2.0 for REST imports, but this checker does not process it. AWS documents REST import support with exceptions.

HTTP APIs have a separate import path and different validation behavior. If your command uses apigatewayv2 import-api, follow the AWS HTTP API import guide. Do not assume a REST workaround applies there. This checker does not convert Swagger 2.0 or OpenAPI 3.1/3.2.

Why a green validator is not the final check

Syntax: can the JSON or YAML be parsed?
OpenAPI structure and meaning: does the document follow its declared specification, with usable references and required fields? Different validators cover different parts of the OpenAPI specification.
Target behavior: can the selected gateway import and use the definition as intended? AWS-specific integrations, authorization, and deployment still need their own verification.

A schema-validation pass is useful evidence, not proof that every layer passed. Conversely, an import that succeeds is not proof that authorization or request validation behaves as intended.

Inspect these REST compatibility gaps

AWS documents the following restrictions in its REST API important notes. These are possible rejection or behavior gaps, not a claim that each one always triggers an import error.

Root security: REST APIs do not apply root-level OpenAPI security. Inspect operation-level requirements. Review inherited security safely
Nullable and schema keywords: fields such as nullable are unsupported. Removing one may change your contract. Preserve null semantics · Review other keywords
External references: AWS does not support references to other files. Bundle the real definitions and check the resulting pointers. Review external references
Model names and paths: gateway naming and path restrictions can be narrower than your source document permits. Check model names · Check path forms

Work from the actual import error

Keep the complete response and original file. Note the API type, operation, and any model, path, or reference named in the response. Use a small synthetic reproduction when asking others for help; remove credentials and private data.
Separate errors from warnings. For REST imports, AWS can roll back on warnings when failonwarnings=true. Disabling that option does not fix an error or restore ignored behavior. Read AWS’s errors and warnings rules
Trace the named object. Check its definition and references before changing it. A missing pointer and an unsupported target are different problems. Inspect internal references
Change one cause at a time. Review the full diff and revalidate. Do not delete security, schemas, or references simply to silence a message.
Retest in a non-production AWS environment. Confirm the imported methods, integrations, and authorization behavior. A local check cannot perform that verification.

What OpenAPI repair can help with

The free Web checker runs deterministic checks on one OpenAPI 3.0 JSON or YAML file, up to 1 MiB, inside your browser. It reports selected structural and REST compatibility findings with source locations. It does not upload your definition or fetch external references.

Its one guarded repair copies root security to eligible, directly declared operations that have no security field. You choose the repair, review the exact preview, then download a new file. The root and explicit operation overrides, including [] and [{}], remain intact.

Other changes stay manual. The checker does not create an AWS authorizer, validate every integration or account setting, connect to AWS, or guarantee import success. Read the full supported checks and limits

Try it without using your own definition

Choose a synthetic example to run its local diagnosis immediately. Only the inherited-security example offers a repair preview; nullable and external references stay manual.

You can also open the checker and choose Try a sample for the original combined example.

Open the free browser-local checker →

Reviewed 6 October 2026. This guide covers selected REST import issues, not every AWS error. Browse all 16 finding guides