This document summarizes the errors that occur when making requests to the Content API, categorized by type.
The information below is not guaranteed to cover all status codes that may occur in the event of an error. Please note that other errors may also occur due to unexpected issues or oversights.
The error response from the Content API may include messages in the response body as follows:
{
message: "some message"
}Error messages are subject to change without notice. Please do not implement handling based on error messages.
Status Code | Error Message | Cause and Solution |
|---|---|---|
400 Bad Request |
| The request was made from an IP address that is not allowed. Check your API IP Restriction settings and make the request from an allowed IP address. |
400 Bad Request |
| The API has been stopped due to either restrictions when downgrading your plan or restrictions when using the Hobby plan. Adjust the number of APIs, Contents, Members, and other items to stay within the limits of your current plan, or upgrade your plan. |
400 Bad Request |
| The request URL contains consecutive slashes immediately after the domain (e.g., https://{SERVICE_ID}.microcms.io//api/v1/blogs). Make sure there is only one slash. |
401 Unauthorized |
| The specified API Key (X-MICROCMS-API-KEY) does not exist for this Service. Specify an API Key listed in the API Key management list. |
404 Not Found | - | The specified API or Content does not exist, or the Content has a status that prevents it from being retrieved (Draft or unpublished). Check that the specified API and Content are correct. |
429 Too Many Requests |
| The API request limit has been exceeded. For solutions, see the help article: What should I do if the API returns a 429 error? |
500 Internal Server Error | - | An unexpected server-side error has occurred. For solutions, see the help article: The API returns a 500-series error. What are the possible causes and solutions? |
502 Bad Gateway | - | An unexpected server-side error has occurred. For solutions, see the help article: The API returns a 500-series error. What are the possible causes and solutions? |
503 Service Unavailable | - | An unexpected server-side error has occurred. For solutions, see the help article: The API returns a 500-series error. What are the possible causes and solutions? |
504 Gateway Timeout | - | The request timed out while being processed. For solutions, see the help article: The API returns a 500-series error. What are the possible causes and solutions? |
Status Code | Error Message | Cause and Solution |
|---|---|---|
400 Bad Request |
| GET operations are not permitted. Check whether GET permission is granted in API Key Settings. |
400 Bad Request |
| An invalid value is specified for the "limit” query parameter. Specify a number between 0 and 100. |
400 Bad Request |
| An invalid value is specified for the "offset” query parameter. Specify a number greater than or equal to 0. |
400 Bad Request |
| The value specified for contains / not_contains in the "filters” query parameter exceeds 2,000 characters. Specify a value of no more than 2,000 characters. The character count is based on the search string after URL decoding. Common Japanese characters and alphanumeric characters are generally counted as one character, but some kanji and emoji may count as more than their visible character count. |
400 Bad Request |
| An invalid value is specified for a query parameter. Check how to specify the query parameters and provide valid values. |
400 Bad Request |
| The response size exceeds the limit (approximately 5 MB). Retrieve the data in multiple requests or retrieve only specific fields. |
414 Request-URI Too Large | - | The request URL exceeds the maximum length limit of 8 KB. Shorten the request URL. |
Status Code | Error Message | Cause and Solution |
|---|---|---|
400 Bad Request |
| POST operations are not permitted. Check whether POST permission has been granted in API Settings. |
400 Bad Request |
| The request body is not valid JSON. Check the JSON syntax and provide it in the correct format. |
400 Bad Request |
| The “status” parameter is not available on your current plan. Upgrade your Plan or remove the “status” parameter. |
400 Bad Request |
| The request body is empty. Prepare the JSON for the content you want to create and provide it as a string in the request body. |
400 Bad Request |
| No user-defined fields are specified in the request body. (Only automatically assigned fields are specified.) Specify at least one defined field. |
400 Bad Request |
| “{fieldId}” cannot be specified because it is not defined in the API Schema. Also, “revisedAt”, “createdAt”, and “updatedAt” cannot be specified because they are assigned automatically. Remove them from the request body. |
400 Bad Request |
| The value specified for “{fieldId}” does not match the data type defined for the field in the API Schema. Specify a value that matches the data type defined in the schema. |
400 Bad Request |
| “publishedAt” can only be specified for Published Content. Remove “publishedAt” or the “status” parameter. |
400 Bad Request |
| The date format specified for “{fieldId}” is invalid. Specify it as a string in ISO format (ISO 8601). |
400 Bad Request |
| “{fieldId}” is required. Include it in the request body. |
400 Bad Request |
| The value specified for “{fieldId}” is already used by another piece of Content. Specify a unique value that is not used by any other Content. |
400 Bad Request |
| The value specified for “{fieldId}” does not match the regular expression configured in the API Schema. Specify a value that matches the configured regular expression. |
400 Bad Request |
| The value specified for “{fieldId}” is below the minimum or exceeds the maximum number of characters allowed, as configured in the API Schema. Check the allowed character count and specify an appropriate value. |
400 Bad Request |
| The value specified for “{fieldId}” is below the minimum or exceeds the maximum number allowed, as configured in the API Schema. Check the allowed number and specify an appropriate value. |
400 Bad Request |
| The value specified for “{fieldId}” is below the minimum value (-9007199254740991) or exceeds the maximum value (9007199254740991) allowed by microCMS. Specify a value within the allowed range. |
400 Bad Request |
| The value specified for “{fieldId}” is not a valid URL. Specify the URL of an image or file uploaded to Media. |
400 Bad Request |
| The value specified for “{fieldId}” is not a valid file URL. Check that the specified file URL is in the correct format. |
400 Bad Request |
| The value specified for “{fieldId}” is not a valid image URL. Check that the specified image URL is in the correct format. |
400 Bad Request |
| The image specified for “{fieldId}” exceeds the image size limit (width). Specify an image smaller than the configured size limit. |
400 Bad Request |
| The image specified for “{fieldId}” cannot be registered because its width cannot be determined. This error occurs when an image size limit is configured. Try using a different format, such as .jpg, .png, or .webp. |
400 Bad Request |
| The image specified for “{fieldId}” exceeds the image size limit (height). Specify an image smaller than the configured size limit. |
400 Bad Request |
| The image specified for “{fieldId}” cannot be registered because its height cannot be determined. This error occurs when an image size limit is configured. Try using a different format, such as .jpg, .png, or .webp. |
400 Bad Request |
| The data exceeds the storage limit (approximately 200 KB). For solutions, see the help article “An error says the content size limit has been exceeded. What should I do?” |
429 Too Many Requests |
| You have exceeded the Content count limit. Adjust the number of pieces of Content to stay within the default limit for your current Plan, or upgrade your Plan. |
Status Code | Error Message | Cause and Solution |
|---|---|---|
400 Bad Request |
| The PUT operation is not permitted. Check whether the PUT permission is granted in API Key Settings. |
400 Bad Request |
| The request body is not valid JSON. Check the JSON syntax and provide it in the correct format. |
400 Bad Request |
| The “status” parameter cannot be specified on your current plan. Either upgrade your Plan or remove the “status” parameter. |
400 Bad Request |
| The request body is empty. Prepare the JSON for the content you want to register and provide it as a string in the request body. |
400 Bad Request |
| No Content ID was specified. Include the Content ID in the request URL. |
400 Bad Request |
| The specified Content ID is already in use by another piece of Content. Change the Content ID. To update existing Content, use the PATCH method. |
400 Bad Request |
| No user-defined Fields are specified in the request body. (Only automatically assigned Fields are specified.) Include at least one defined Field. |
400 Bad Request |
| The specified Content ID contains an invalid value. Change the Content ID. |
400 Bad Request |
| The specified Content ID is in an invalid format. Check the Content ID settings and provide it in the correct format. |
400 Bad Request |
| “{fieldId}” cannot be specified because it is not defined in the API Schema. Also, “revisedAt”, “createdAt”, and “updatedAt” cannot be specified because they are assigned automatically. Remove them from the request body. |
400 Bad Request |
| The value specified for “{fieldId}” does not match the data type of the Field defined in the API Schema. Specify a value that matches the data type defined in the schema. |
400 Bad Request |
| “publishedAt” can only be specified for Published Content. Remove “publishedAt” or the “status” parameter. |
400 Bad Request |
| The date format specified for “{fieldId}” is invalid. Specify it as an ISO-formatted (ISO 8601) string. |
400 Bad Request |
| “{fieldId}” is required. Include it in the request body. |
400 Bad Request |
| The value specified for “{fieldId}” is already registered for another piece of Content. Specify a unique value that is not used by any other Content. |
400 Bad Request |
| The value specified for “{fieldId}” does not match the regular expression configured in the API Schema. Specify a value that matches the configured regular expression. |
400 Bad Request |
| The value specified for “{fieldId}” is below the minimum or exceeds the maximum number of characters allowed, as configured in the API Schema. Check the allowed character count and specify an appropriate value. |
400 Bad Request |
| The value specified for “{fieldId}” is below the minimum or exceeds the maximum number of items allowed, as configured in the API Schema. Check the allowed number of items and specify an appropriate value. |
400 Bad Request |
| The value specified for “{fieldId}” is below the minimum value (-9007199254740991) or exceeds the maximum value (9007199254740991) allowed by microCMS. Specify a value within the allowed range. |
400 Bad Request |
| The value specified for “{fieldId}” is not a valid URL. Specify the URL of an image or file uploaded to Media. |
400 Bad Request |
| The value specified for “{fieldId}” is not a valid file URL. Check that the specified file URL is in the correct format. |
400 Bad Request |
| The value specified for “{fieldId}” is not a valid image URL. Check that the specified image URL is in the correct format. |
400 Bad Request |
| The image specified for “{fieldId}” exceeds the image size limit (width). Specify an image smaller than the configured size limit. |
400 Bad Request |
| The image specified for “{fieldId}” cannot be registered because its width cannot be determined from its format. This error occurs when an image size limit is configured. Try using another format, such as .jpg, .png, or .webp. |
400 Bad Request |
| The image specified for “{fieldId}” exceeds the image size limit (height). Specify an image smaller than the configured size limit. |
400 Bad Request |
| The image specified for “{fieldId}” cannot be registered because its height cannot be determined from its format. This error occurs when an image size limit is configured. Try using another format, such as .jpg, .png, or .webp. |
400 Bad Request |
| The data exceeds the storage limit (approximately 200 KB). For solutions, see the help article: “An error says the content size limit has been exceeded. What should I do?” |
429 Too Many Requests |
| You have exceeded the Content count limit. Adjust the number of Content items to stay within the default limit for your current Plan, or upgrade your Plan. |
Status Code | Error Message | Cause and Solution |
|---|---|---|
400 Bad Request |
| PATCH operations are not permitted. Check whether PATCH permissions have been granted in API Key Settings. |
400 Bad Request |
| The request body is not valid JSON. Check the JSON syntax and provide it in the correct format. |
400 Bad Request |
| The specified Content does not exist. Check that the correct Content ID is specified. |
400 Bad Request |
| The request body is empty. Prepare the JSON for the content you want to register and provide it as a string in the request body. |
400 Bad Request |
| “{fieldId}” cannot be specified because it is not defined in the API Schema. Also, “revisedAt”, “createdAt”, and “updatedAt” are automatically assigned values and cannot be specified. Remove them from the request body. |
400 Bad Request |
| The value specified for “{fieldId}” does not match the data type of the Field defined in the API Schema. Specify a value that matches the data type defined in the schema. |
400 Bad Request |
| “publishedAt” can only be specified for Published Content. Remove “publishedAt” from the request. |
400 Bad Request |
| The date format specified for “{fieldId}” is incorrect. Specify it as an ISO 8601 string. |
400 Bad Request |
| The value specified for “{fieldId}” is already registered for another Content. Specify a unique value that is not used by any other Content. |
400 Bad Request |
| The value specified for “{fieldId}” does not match the regular expression configured in the API Schema. Specify a value that matches the configured regular expression. |
400 Bad Request |
| The value specified for “{fieldId}” is below the minimum or exceeds the maximum number of characters allowed, as configured in the API Schema. Check the allowed character count and specify an appropriate value. |
400 Bad Request |
| The value specified for “{fieldId}” is below the minimum or exceeds the maximum number of items allowed, as configured in the API Schema. Check the allowed number of items and specify an appropriate value. |
400 Bad Request |
| The value specified for “{fieldId}” is below the minimum value (-9007199254740991) or exceeds the maximum value (9007199254740991) set by microCMS. Specify a value within the allowed range. |
400 Bad Request |
| The value specified for “{fieldId}” is not a valid URL. Specify the URL of an image or file uploaded to Media. |
400 Bad Request |
| The value specified for “{fieldId}” is not a valid file URL. Check that the specified file URL is in the correct format. |
400 Bad Request |
| The value specified for “{fieldId}” is not a valid image URL. Check that the specified image URL is in the correct format. |
400 Bad Request |
| The image specified for “{fieldId}” exceeds the image size limit (width). Specify an image smaller than the size limit configured for the image. |
400 Bad Request |
| The image specified for “{fieldId}” cannot be registered because its width cannot be determined from its format. This error occurs when an image size limit is configured. Try changing it to another format, such as .jpg, .png, or .webp. |
400 Bad Request |
| The image specified for “{fieldId}” exceeds the image size limit (height). Specify an image smaller than the size limit configured for the image. |
400 Bad Request |
| The image specified for “{fieldId}” cannot be registered because its height cannot be determined from its format. This error occurs when an image size limit is configured. Try changing it to another format, such as .jpg, .png, or .webp. |
400 Bad Request |
| The data exceeds the save limit (approximately 200 KB). For solutions, see the help article “I get an error saying the content size limit has been exceeded. What should I do?” |
400 Bad Request |
| The status of Content whose publication has ended cannot be updated via the API. Update it from the Administration console. |
Status Code | Error Message | Cause and Solution |
|---|---|---|
400 Bad Request |
| The DELETE operation is not permitted. Check whether the DELETE permission is granted in API Settings. |
400 Bad Request |
| The specified Content does not exist. Check that the correct Content ID is specified. |
400 Bad Request |
| The Content cannot be deleted because it is referenced by other Content. Remove the reference to the Content you want to delete from the referencing Content. |