アクセスいただきありがとうございます。こちらのページは現在英語のみのご用意となっております。順次日本語化を進めてまいりますので、ご理解のほどよろしくお願いいたします。

SMAPI Error Codes

The Alexa Skill Management API (SMAPI) provides RESTful HTTP interfaces for programmatically performing Alexa skill management tasks, such as creating a new skill or updating an interaction model. When a problem occurs, SMAPI returns an HTTP response with a 4xx or 5xx HTTP status code. Some of these error responses include an error object, in JSON format, in the response body. The error object contains a code and a validationDetails object that you can use to programmatically respond to the error.

Error object structure

Each error object contains the following fields:

  • code – A machine-readable string that uniquely identifies the category of validation that failed. For the full list of possible values, see List of error codes.
  • validationDetails – A machine-readable object that contains details about why the validation failed, and where in the developer-provided resource the failure occurred.
  • message – A human-readable string that explains the validation failure.

List of error codes

The following list contains all the error code values that SMAPI can send in an error response. Each error code value is a link to more details and examples.

Error object details and examples

The following sections contain details and examples for each of the possible error codes.

CONFLICTING_INSTANCES

SMAPI returns a CONFLICTING_INSTANCES error code when the presence or value of one field in the request conflicts with the presence or value of another field.

The following example shows the error object when a developer-provided skill manifest sets isAvailableWorldwide to true, but also contains a value for distributionCountries.

{
  "error": {
    "code": "CONFLICTING_INSTANCES",
    "message": "Instance at \"$.manifest.publishingInformation.distributionCountries\" is not expected when boolean instance with value \"true\" at property path \"$.manifest.publishingInformation.isAvailableWorldwide\" is present.",
    "validationDetails": {
      "originalInstance": {
        "propertyPath": "$.manifest.publishingInformation.isAvailableWorldwide",
        "dataType": "boolean",
        "value": true
      },
      "conflictingInstance": {
        "propertyPath": "$.manifest.publishingInformation.distributionCountries"
      }
    }
  }
}

DENIED_FEATURE_ACCESS

SMAPI returns a DENIED_FEATURE_ACCESS error code when the request contains a publicly known feature that's available only to whitelisted developers, but the requesting developer is not whitelisted. The error message or validationDetails object might contain contact information to request access to the feature.

The following example shows the error object when a developer-provided skill manifest contains a category value that the requesting developer is not whitelisted to access.

{
  "error": {
    "code": "DENIED_FEATURE_ACCESS",
    "message": "User is not whitelisted for the \"Example Whitelist Only Category\" feature and, therefore, cannot use string instance with value \"EXAMPLE_WHITELIST_ONLY\" at \"$.manifest.publishingInformation.category\". Further information: \"example-request-access@amazon.com\"",
    "validationDetails": {
      "originalInstance": {
        "propertyPath": "$.manifest.publishingInformation.category",
        "dataType": "string",
        "value": "EXAMPLE_WHITELIST_ONLY"
      },
      "feature": {
        "name": "Example Whitelist Only Category",
        "contact": "example-request-access@amazon.com"
      }
    }
  }
}

The following example shows the error object when a developer-provided skill manifest contains an interface that the requesting developer is not whitelisted to access.

{
  "error": {
    "code": "DENIED_FEATURE_ACCESS",
    "message": "User is not whitelisted for the \"Example Whitelist Only Interface\" feature and, therefore, cannot use instance at \"$.manifest.apis.custom.exampleInterface\"",
    "validationDetails": {
      "originalInstance": {
        "propertyPath": "$.manifest.apis.custom.exampleInterface"
      },
      "feature": {
        "name": "Example Whitelist Only Interface"
      }
    }
  }
}

DUPLICATE_ARRAY_ITEMS

SMAPI returns a DUPLICATE_ARRAY_ITEMS error code when the request contains duplicate items or properties in a developer-provided array.

The following example shows the error object when a developer-provided skill manifest contains duplicate url values in the feeds array.

{
  "error": {
    "code": "DUPLICATE_ARRAY_ITEMS",
    "message": "Array item at property path \"$.manifest.apis.flashBriefing.locales.en-US.feeds[1].url\" and array item at property path \"$.manifest.apis.flashBriefing.locales.en-US.feeds[3].url\" have the same value: \"www.example.com/rss\". Item values must be unique.",
    "validationDetails": {
      "originalInstance": {
        "propertyPath": "$.manifest.apis.flashBriefing.locales.en-US.feeds[1].url",
        "dataType": "string",
        "value": "www.example.com/rss"
      },
      "conflictingInstance": {
        "propertyPath": "$.manifest.apis.flashBriefing.locales.en-US.feeds[3].url",
        "dataType": "string",
        "value": "www.example.com/rss"
      }
    }
  }
}

EXPECTED_COMPLIANCE_AGREEMENT

SMAPI returns an EXPECTED_COMPLIANCE_AGREEMENT error code when the skill is not compliant with one of the mandatory agreements. For example, this error might be returned when the skill developer has not certified that the skill is export compliant.

The following example shows the error object when the skill must be export compliant, but the developer-provided skill manifest specifies that isExportCompliant is false.

{
  "error": {
    "code": "EXPECTED_COMPLIANCE_AGREEMENT",
    "message": "The skill must be export compliant. By setting boolean instance at \"$.manifest.privacyAndCompliance.isExportCompliant\" to true, you certify the following: \"I certify that this Alexa skill may be imported to and exported from the United States and all other countries and regions in which Alexa operates its program or in which I've authorized sales to end users (without the need for Amazon to obtain any license or clearance or take any other action) and is in full compliance with all applicable laws and regulations governing imports and exports, including those applicable to software that makes use of encryption technology.\""
  },
  "validationDetails": {
    "agreementType": "EXPORT_COMPLIANCE"
  }
}

SMAPI returns an EXPECTED_RELATED_INSTANCE error code when the presence or value of one developer-provided field does not match the expectations that are determined by the presence or value of another developer-provided field.

The following example shows the error object when a developer-provided skill manifest uses the Smart Home API but does not set the skill's category as SMART_HOME.

{
  "error": {
    "code": "EXPECTED_RELATED_INSTANCE",
    "message": "String instance with value \"SMART_HOME\" at property path \"$.manifest.publishingInformation.category\" is expected to be present when instance at property path \"$.manifest.apis.smartHome\" is present",
    "validationDetails": {
      "originalInstance": {
        "propertyPath": "$.manifest.apis.smartHome"
      },
      "expectedInstance": {
        "propertyPath": "$.manifest.publishingInformation.category",
        "dataType": "string",
        "value": "SMART_HOME"
      }
    }
  }
}

INCONSISTENT_ENDPOINTS

SMAPI returns an INCONSISTENT_ENDPOINTS error code when the request contains different types of endpoints but they are expected to be the same.

The following example shows the error object when a developer-provided skill manifest specifies an endpoint as an HTTP URL in one location, but as an Amazon Resource Name (ARN) in another location.

{
  "error": {
    "code": "INCONSISTENT_ENDPOINTS",
    "message": "Endpoint of value \"https://www.example.com\" at property path \"$.manifest.apis.custom.endpoint.uri\" is not of same type as endpoint of value \"arn:aws:lambda:us-east-1:123456789012:function:example-function\" at property path  \"$.manifest.apis.custom.regions.na.endpoint.uri\": Original type: \"https\", Inconsistent type:\"arn\".",
    "validationDetails": {
      "originalEndpoint": {
        "propertyPath": "$.manifest.apis.custom.endpoint.uri",
        "value": "https://www.example.com",
        "type": "https"
      },
      "inconsistentEndpoint": {
        "propertyPath": "$.manifest.apis.custom.regions.na.endpoint.uri",
        "value": "arn:aws:lambda:us-east-1:123456789012:function:example-function",
        "type": "arn"
      }
    }
  }
}

INVALID_ARRAY_SIZE

SMAPI returns an INVALID_ARRAY_SIZE error code when the number of items in a developer-provided collection is not within the range that is allowed by the validation.

The following example shows the error object when a developer-provided skill manifest contains no example phrases, but the validation requires at least one example phrase.

{
  "error": {
    "code": "INVALID_ARRAY_SIZE",
    "message": "Size of Array instance at property path \"$.manifest.publishingInformation.locales.en-US.examplePhrases\" is outside the allowed range: Actual number of items: 0, Minimum number of items: 1.",
    "validationDetails": {
      "originalInstance": {
        "propertyPath": "$.manifest.publishingInformation.locales.en-US.examplePhrases"
      },
      "actualNumberOfItems": 0,
      "minimumNumberOfItems": 1
    }
  }
}

The following example shows the error object when a developer-provided skill manifest contains too many example phrases.

{
  "error": {
    "code": "INVALID_ARRAY_SIZE",
    "message": "Size of Array instance at property path \"$.manifest.publishingInformation.locales.en-US.examplePhrases\" is outside the allowed range: Actual number of items: 10, Maxmimum number of items: 4",
    "validationDetails": {
      "originalInstance": {
        "propertyPath": "$.manifest.publishingInformation.locales.en-US.examplePhrases"
      },
      "actualNumberOfItems": 10,
      "maximumNumberOfItems": 4
    }
  }
}

INVALID_CONTENT_TYPE

SMAPI returns an INVALID_CONTENT_TYPE error code when the media type of a resource found at a developer-provided URL does not match the content type that is expected or allowed by the validation.

The following example shows the error object when the image at a developer-provided URL does not match any of the allowed image types.

{
  "error": {
    "code": "INVALID_CONTENT_TYPE",
    "message": "Resource with identifier \"https://www.example.com/smallIconUri\" at property path \"$.manifest.publishingInformation.locales.en-US.smallIconUri\" has invalid content type. Allowed content types: [\"image/png\", \"image/jpg\"]",
    "validationDetails": {
      "originalInstance": {
        "propertyPath": "$.manifest.publishingInformation.locales.en-US.smallIconUri",
        "dataType": "string",
        "value": "https://www.example.com/smallIconUri"
      },
      "allowedContentTypes": [
        "image/png",
        "image/jpg"
      ]
    }
  }
}

INVALID_DATA_TYPE

SMAPI returns an INVALID_DATA_TYPE error code when the data type of a developer-provided value does not match the data type that is expected or allowed by the validation.

The following example shows the error object when the data type in a developer-provided skill manifest does not match the allowed data type.

{
  "error": {
    "code": "INVALID_DATA_TYPE",
    "message": "Instance at property path \"$.manifest.publishingInformation.distributionCountries\" of type \"string\" does not match any allowed primitive types [\"array\"].",
    "validationDetails": {
      "originalInstance": {
        "propertyPath": "$.manifest.publishingInformation.distributionCountries",
        "dataType": "string"
      },
      "allowedDataTypes": [
        "array"
      ]
    }
  }
}

INVALID_ENUM_VALUE

SMAPI returns an INVALID_ENUM_VALUE error code when a developer-provided value does not match any of the elements in the enumeration (the set of allowed values).

The following example shows the error object when a developer-provided enumeration value in a skill manifest does not match any of the allowed values.

{
  "error": {
    "code": "INVALID_ENUM_VALUE",
    "message": "String instance at property path \"$.manifest.publishingInformation.distributionCountries[0]\" has invalid enum value: \"UAA\"",
    "validationDetails": {
      "originalInstance": {
        "propertyPath": "$.manifest.publishingInformation.distributionCountries[0]",
        "dataType": "string",
        "value": "UAA"
      }
    }
  }
}

INVALID_IMAGE_ATTRIBUTES

SMAPI returns an INVALID_IMAGE_ATTRIBUTES error code when one or more attributes of a developer-provided image does not match the attributes that are expected or allowed by the validation.

The following example shows the error object when a developer-provided image does not match one of the allowed image dimensions.

{
  "error": {
    "code": "INVALID_IMAGE_ATTRIBUTES",
    "message": "Image with identifier \"www.example.com\" at property path \"$.manifest.publishingInformation.locales.en-US.largeIconUri\" is invalid.\nExpected dimensions: \"[512x512, 108x108]\"\nMaximum allowed size, respectively: \"[2.8MB, 2.0MB]\".\nFound image of dimension \"512x511\", of size \"2.8MB\".",
    "validationDetails": {
      "originalInstance": {
        "propertyPath": "$.manifest.publishingInformation.locales.en-US.largeIconUri",
        "dataType": "string",
        "value": "www.example.com"
      },
      "actualImageAttributes": {
        "dimension": {
          "widthInPixels": 511,
          "heightInPixels": 512
        },
        "size": {
          "value": 2.8,
          "unit": "MB"
        }
      },
      "allowedImageAttributes": [
        {
          "dimension": {
            "widthInPixels": 512,
            "heightInPixels": 512
          },
          "maximumSize": {
            "value": 2.8,
            "unit": "MB"
          }
        },
        {
          "dimension": {
            "widthInPixels": 108,
            "heightInPixels": 108
          },
          "maximumSize": {
            "value": 2.0,
            "unit": "MB"
          }
        }
      ]
    }
  }
}

INVALID_INTEGER_VALUE

SMAPI returns an INVALID_INTEGER_VALUE error code when a developer-provided integer value does not match any of the allowed values.

The following examples show the error object when a developer-provided integer is outside the range of allowed values.

{
  "error": {
    "code": "INVALID_INTEGER_VALUE",
    "message": "Integer instance at property path \"$.manifest.publishingInformation.authorizationNumber\" is outside the allowed range: Actual value: 1, Minimum value: 10.",
    "validationDetails": {
      "originalInstance": {
        "propertyPath": "$.manifest.publishingInformation.authorizationNumber",
        "dataType": "integer",
        "value": 1
      },
      "minimumIntegerValue": 10
    }
  }
}
{
  "error": {
    "code": "INVALID_INTEGER_VALUE",
    "message": "Integer instance at property path \"$.manifest.publishingInformation.gadgetSupport.maxGadgetButtons\" is outside the allowed range: Actual value: 7, Maximum value: 4",
    "validationDetails": {
      "originalInstance": {
        "propertyPath": "$.manifest.publishingInformation.gadgetSupport.maxGadgetButtons",
        "dataType": "integer",
        "value": 7
      },
      "maximumIntegerValue": 4
    }
  }
}

INVALID_STRING_LENGTH

SMAPI returns an INVALID_STRING_LENGTH error code when the length of a developer-provided string is shorter or longer than the length allowed by the validation.

The following examples show the error object when the developer-provided skill manifest contains an example phrase that is too short (first example) and too long (second example).

{
  "error": {
    "code": "INVALID_STRING_LENGTH",
    "message": "Length of String instance with value \"a\" at property path \"$.manifest.publishingInformation.locales.en-US.examplePhrases[1]\" is outside the allowed range: Actual length: 1, Minimum length: 2.",
    "validationDetails": {
      "originalInstance": {
        "propertyPath": "$.manifest.publishingInformation.locales.en-US.examplePhrases[1]",
        "dataType": "string",
        "value": "a"
      },
      "actualStringLength": 1,
      "minimumStringLength": 2
    }
  }
}
{
  "error": {
    "code": "INVALID_STRING_LENGTH",
    "message": "String instance with value \"Example Custom Skill Name Example Custom Skill Name Example Custom Skill Name Example Custom Skill Name Example Custom Skill Name Example Custom Skill Name\" at property path \"$.manifest.publishingInformation.locales.en-US.name\" is outside the allowed range: Actual length: 155, Maximum length: 50.",
    "validationDetails": {
      "originalInstance": {
        "propertyPath": "$.manifest.publishingInformation.locales.en-US.name",
        "dataType": "string",
        "value": "Example Custom Skill Name Example Custom Skill Name Example Custom Skill Name Example Custom Skill Name Example Custom Skill Name Example Custom Skill Name"
      },
      "actualStringLength": 155,
      "maximumStringLength": 50
    }
  }
}

INVALID_STRING_PATTERN

SMAPI returns an INVALID_STRING_PATTERN error code when a developer-provided string does not match the pattern that is expected or allowed by the validation. The error object includes the expected pattern as a regular expression.

The following example shows the error object when a developer-provided skill manifest contains an endpoint value that does not start with the expected arn prefix.

{
  "error": {
    "code": "INVALID_STRING_PATTERN",
    "message": "String instance with value \"*.123\" at property path \"$.manifest.music.endpoint\" does not match the regular expression: \"^arn\".",
    "validationDetails": {
      "originalInstance": {
        "propertyPath": "$.manifest.music.endpoint",
        "dataType": "string",
        "value": "*.123"
      },
      "expectedRegexPattern": "^arn"
    }
  }
}

INVALID_URL_DOMAIN

SMAPI returns an INVALID_URL_DOMAIN error code when a developer-provided domain name is not valid according to RFC 1034 section 3 and RFC 1123 section 2.1.

The following example shows the error object when a developer-provided domain name is not valid.

{
  "error": {
    "code": "INVALID_URL_DOMAIN",
    "message": "String instance with value \"www.example.con\" at property path \"$.manifest.accountLinking.domains[2]\" is not a valid URL domain.",
    "validationDetails": {
      "originalInstance": {
        "propertyPath": "$.manifest.accountLinking.domains[2]",
        "dataType": "string",
        "value": "www.example.con"
      }
    }
  }
}

INVALID_URL_FORMAT

SMAPI returns an INVALID_URL_FORMAT error code when a developer-provided URL is not valid.

The following example shows the error object when a developer-provided URL is not valid.

{
  "error": {
    "code": "INVALID_URL_FORMAT",
    "message": "String instance with value \"httpa://www.myprivacypolicy.example.com\" at property path \"$.manifest.privacyAndCompliance.locales.en-US.privacyPolicyUrl\" is not a valid URL.",
    "validationDetails": {
      "originalInstance": {
        "propertyPath": "$.manifest.privacyAndCompliance.locales.en-US.privacyPolicyUrl",
        "dataType": "string",
        "value": "httpa://www.myprivacypolicy.example.com"
      }
    }
  }
}

MISSING_REQUIRED_PROPERTY

SMAPI returns a MISSING_REQUIRED_PROPERTY error code when the request fails to provide an object or property that is required. When the property is present and doesn't contain any values, but at least one is required by the validation, SMAPI returns an UNEXPECTED_EMPTY_OBJECT error.

The following example shows the error object when a developer-provided skill manifest does not contain the required publishingInformation object.

{
  "error": {
    "code": "MISSING_REQUIRED_PROPERTY",
    "message": "Object instance at property path \"$.manifest\" has missing required property: \"publishingInformation\"",
    "validationDetails": {
      "originalInstance": {
        "propertyPath": "$.manifest"
      },
      "requiredProperty": "publishingInformation"
    }
  }
}

MUTUALLY_EXCLUSIVE_ARRAY_ITEMS

SMAPI returns a MUTUALLY_EXCLUSIVE_ARRAY_ITEMS error code when two or more items or properties in a developer-provided array are incompatible with each other.

The following example shows the error object when a developer-provided skill manifest contains overlapping permission scopes in the permissions array.

{
  "error": {
    "code": "MUTUALLY_EXCLUSIVE_ARRAY_ITEMS",
    "message": "Array item at property path \"$.manifest.apis.permissions[0]\" with value \"alexa::devices:all:address:full:read\" cannot coexist in array with array item at \"$.manifest.apis.permissions[3]\" with value \"alexa:devices:all:address:country_and_postal_code:read\"",
    "validationDetails": {
      "originalInstance": {
        "propertyPath": "$.manifest.apis.permissions[0]",
        "dataType": "string",
        "value": "alexa::devices:all:address:full:read"
      },
      "conflictingInstance": {
        "propertyPath": "$.manifest.apis.permissions[3]",
        "dataType": "string",
        "value": "alexa:devices:all:address:country_and_postal_code:read"
      }
    }
  }
}

RESOURCE_NOT_FOUND

SMAPI returns a RESOURCE_NOT_FOUND error code when no resource is found at a developer-provided resource identifier. Resource identifiers include URLs, Amazon Resource Names (ARNs), and UUIDs.

The following example shows the error object when the resource at a developer-provided URL cannot be found.

{
  "error": {
    "code": "RESOURCE_NOT_FOUND",
    "message": "Resource with identifier \"www.example.com/rss\" at property path \"$.manifest.publishingInformation.locales.en-Us.feeds[0].uri\" was not found.",
    "validationDetails": {
      "originalInstance": {
        "propertyPath": "$.manifest.publishingInformation.locales.en-Us.feeds[0].uri",
        "dataType": "string",
        "value": "www.example.com/rss"
      }
    }
  }
}

UNEXPECTED_EMPTY_OBJECT

SMAPI returns an UNEXPECTED_EMPTY_OBJECT error code when the request fails to provide any values for a property, but at least one is expected by the validation. When the property itself is missing but required, SMAPI returns a MISSING_REQUIRED_PROPERTY error.

The following example shows the error object when a developer-provided skill manifest does not contain any information in the apis object.

{
  "error": {
    "code": "UNEXPECTED_EMPTY_OBJECT",
    "message": "Object instance at property path \"$.manifest.apis\" has no property defined.",
    "validationDetails": {
      "originalInstance": {
        "propertyPath": "$.manifest.apis"
      }
    }
  }
}

UNEXPECTED_PROPERTY

SMAPI returns an UNEXPECTED_PROPERTY error code when the request provides an object, field, or property that is not expected by the validation.

The following example shows the error object when a developer-provided skill manifest contains a typo ("privacyPolicyUr" instead of "privacyPolicyUrl").

{
  "error": {
    "code": "UNEXPECTED_PROPERTY",
    "message": "Object instance at property path \"$.manifest.privacyAndCompliance.locales.en-US\" has unexpected property: \"privacyPolicyUr\"",
    "validationDetails": {
      "originalInstance": {
        "propertyPath": "$.manifest.privacyAndCompliance.locales.en-US"
      },
      "unexpectedProperty": "privacyPolicyUr"
    }
  }
}