Amazon API Gateway
Developer Guide

Known Issues

  • The plain text pipe character (|) is not supported for any request URL query string and must be URL-encoded.

  • Paths of /ping and /sping are reserved for the service health check. Use of these for API root-level resources with custom domains will fail to produce the expected result.

  • Cross-account authentication is not currently supported in API Gateway. An API caller must be an IAM user of the same AWS account of the API owner.

  • When using the API Gateway console to test an API, you may get an "unknown endpoint errors" response if a self-signed certificate is presented to the backend, the intermediate certificate is missing from the certificate chain, or any other unrecognizable certificate-related exceptions thrown by the backend.

  • The following backends may not support SSL client authentication in a compatible way with API Gateway:

  • API Gateway supports most of the Swagger specification, with the following exceptions:

    • API Gateway models are defined using JSON Schema, instead of the JSON schema used by Swagger.

    • The additionalProperties field is not supported in Models.

    • The allOf field is not supported in Models.

    • The readOnly field is not supported in Models.

    • The discriminator parameter is not supported in any schema object.

    • The example tag is not supported.

    • The maxItems and minItems tags are not included in simple request validation. To work around this, update the model after import before doing validation.

    • The readOnly field is not supported.

    • Response definitions of the "500": {"$ref": "#/responses/UnexpectedError"} form is not supported in the Swagger document root. To work around this, replace the reference by the inline schema.

    • Numbers of the Int32 or Int64 type is not supported. An example is shown as follows:

      "elementId": { "description": "Working Element Id", "format": "int32", "type": "number" }
    • Decimal number format type ("format": "decimal") is not supported in a schema definition.

    • In method responses, schema definition must be of an object type and cannot be of primitive types. For example, "schema": { "type": "string"} is not supported. However, you can work around this using the following object type:

      "schema": { "$ref": "#/definitions/StringResponse" } "definitions": { "StringResponse": { "type": "string" } }
  • API Gateway enacts the following restrictions and limitations when handling methods with either Lambda proxy integration or HTTP proxy integration.

    • Duplicated query string parameters are not supported.

    • Duplicated headers are not supported.

    • The Host header will not be forwarded to HTTP endpoints.

    • The following headers may be remapped to x-amzn-Remapped-HEADER when sent to your integration endpoint or sent back by your integration endpoint:

      • Accept

      • Accept-Charset

      • Accept-Encoding

      • Age

      • Authorization

      • Connection

      • Content-Encoding

      • Content-Length

      • Content-MD5

      • Content-Type

      • Date

      • Expect

      • Host

      • Max-Forwards

      • Pragma

      • Proxy-Authenticate

      • Range

      • Referer

      • Server

      • TE

      • Trailer

      • Transfer-Encoding

      • Upgrade

      • User-Agent

      • Via

      • Warn

      • WWW-Authenticate

  • The Android SDK of an API generated by API Gateway uses the class. This class will throw an unhandled exception, on devices running Android 4.4 and earlier, for a 401 response resulted from remapping of the WWW-Authenticate header to X-Amzn-Remapped-WWW-Authenticate.

  • Unlike API Gateway-generated Java, Android and iOS SDKs of an API, the JavaScript SDK of an API generated by API Gateway does not support retries for 500-level errors.

  • The test invocation of a method uses the default content type of application/json and ignores specifications of any other content types.