microCMS
Documentation
  • Pricing
  • Blog
  • FAQ
  • Contact
  • Sign In
  • Get started for free
Navigation
Tutorial
Next.js
  • Integration with Next.js
  • Getting Started with App Router
  • Tutorial (App Router)
  • Getting Started with Pages Router
  • Tutorial (Pages Router)
Astro
  • Getting Started
  • Integration with Astro
  • Tutorial
Nuxt
  • Integration with Nuxt
  • Getting Started
  • Tutorial
Gatsby
  • Integration with Gatsby
  • Getting Started
  • Tutorial
JavaScript
  • Integration with JavaScript
  • Getting Started (Browser)
  • Getting Started (Server)
PHP
  • Integration with PHP
  • Getting Started
Ruby
  • Integration with Ruby
  • Getting Started
Go
  • Integration with Go
  • Getting Started with microCMS
Manual
  • Introduction
Account & Login
  • Account Registration
  • Login
  • Email Address Authentication
Services
  • Creating a Service
  • Service Configuration
  • Template
  • Service Deletion
Payment
  • Change of Pricing Plan
  • Registering and Changing Payment Methods
API
  • Creating and Managing APIs
  • API Settings
  • Export/Import of API Schema
Fields
  • Text Field
  • Text Area
  • Image
  • Multiple Images
  • Date
  • Boolean
  • Selectable Field
  • Content Reference
  • Multiple Content References
  • Number
  • File
  • Extended Field
  • Repetition
  • Custom
Contents
  • CSV Export of Content
  • Content Creation
  • Content Editing
  • Content Management
  • View
  • Content Status
  • Custom Status
  • Setting the Content ID
  • Automatically Assigned Values for Content
  • CSV Import of Content
  • API Preview
  • Examples of Using Query Parameters with API Preview
  • Integration Methods by Rendering Type
  • Screen Preview
  • Setting Up Webhooks for Content
Rich Editor
  • How to Use the Rich Editor
  • Rich Editor WRITE API
  • How to Use the Old Rich Editor
Reviews
  • Review
  • AI Review
Media
  • Media Management
  • Changing Media Filters and Display Order
  • Media Tag Configuration
  • Setting Up Media Webhooks
  • Custom Domain Settings for Media
Permission Management
  • Member Management
  • Roles (Permission Management in the Admin Panel)
Environments
  • Multiple Environments (Development Environment)
  • Merging API Settings Between Environments
Connection
  • Amazon S3 Integration
Logs
  • Audit Log
  • Data Transfer Volume
Security
  • Content Update History
  • IP Restrictions for Management Dashboard
  • IP Restrictions for APIs
Authentication
  • Setting Up Two-Factor Authentication
  • Mandatory Two-Factor Authentication
  • Single Sign-On
Specifications & Limitations
  • Recommended Environment
  • Limitations / Precautions
Content API
  • What is the Content API?
Basic Operations
  • GET /api/v1/{endpoint}
  • GET /api/v1/{endpoint}/{content_id}
  • POST /api/v1/{endpoint}
  • PUT /api/v1/{endpoint}/{content_id}
  • PATCH /api/v1/{endpoint}/{content_id}
  • DELETE /api/v1/{endpoint}/{content_id}
API Keys
  • API Key (API Authentication and Authorization Management)
  • Migration from the Old API (X-API-KEY, etc.)
Responses & Error Handling
  • Response format for each field in the GET API
  • Specifying Query Parameters in the GET API
  • Error Responses of the Content API
Management API (Beta)
  • POST /api/v1/roles
  • DELETE /api/v1/roles/{role_id}
  • GET /api/v1/roles/{role_id}
  • PATCH /api/v1/roles/{role_id}
  • GET /api/v1/roles
  • What is the Management API?
Content Operations
  • PUT /api/v1/contents/{endpoint}/{content_id}/reservation
  • GET /api/v1/contents/{endpoint}
  • GET /api/v1/contents/{endpoint}/{content_id}
  • PATCH /api/v1/contents/{endpoint}/{content_id}/status
  • PATCH /api/v1/contents/{endpoint}/{content_id}/createdBy
Media Operations
  • GET /api/v2/media
  • GET /api/v1/media
  • POST /api/v1/media
  • DELETE /api/v2/media
Member Operations
  • PATCH /api/v1/members/{member_id}
  • GET /api/v1/members
  • GET /api/v1/members/{member_id}
API Operations
  • POST /api/v1/apis
  • GET /api/v1/apis
  • GET /api/v1/apis/{endpoint}
Service Operations
  • GET /api/v1/service
Responses & Error Handling
  • Management API Error Responses
Image API
  • What is the Image API?
Parameters
  • Image Size
  • Quality
  • Resolution and Screen Size
  • Format
  • Text
  • Border
  • Padding
  • Shape
  • Download
  • Watermark
MCP Server
  • microCMS MCP
  • microCMS Document MCP Server
  • Top
  • Content API

Error Responses of the Content API

Last updated: 2026/11/20

This document summarizes the errors that occur when making requests to the Content API, categorized by type.

Warning

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.

Response Body on Error

The error response from the Content API may include messages in the response body as follows:

{
    message: "some message"
}
Warning

Error messages are subject to change without notice. Please do not implement handling based on error messages.

List of Error Responses

Common Error Responses for All Methods

Status Code

Error Message

Cause and Solution

400 Bad Request

IP address rejected.

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

API is stopped for xxxxxxxx service. Please upgrade your plan.

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

Invalid 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

X-MICROCMS-API-KEY header is invalid.

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.

To retrieve Draft Content, grant the permission to retrieve all Draft Content. To retrieve a single Draft item, use the "draftKey" parameter.

To retrieve unpublished Content, grant the permission to retrieve all unpublished Content.

429 Too Many Requests

Too many requests, please try again later.

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?

GET Method Error Response

Status Code

Error Message

Cause and Solution

400 Bad Request

GET is forbidden.

GET operations are not permitted. Check whether GET permission is granted in API Key Settings.

400 Bad Request

Invalid 'limit' value.

An invalid value is specified for the "limit” query parameter. Specify a number between 0 and 100.

400 Bad Request

Invalid 'offset' value.

An invalid value is specified for the "offset” query parameter. Specify a number greater than or equal to 0.

400 Bad Request

Invalid 'filters' value. The value for 'contains' or 'not_contains' should not exceed 2000 characters.

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

invalid parameter.

An invalid value is specified for a query parameter. Check how to specify the query parameters and provide valid values.

How to specify GET /api/v1/{endpoint}
How to specify GET /api/v1/{endpoint}/{content_id}

400 Bad Request

Response body size is too long. Check your url parameters.

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.

Error Responses for POST Method

Status Code

Error Message

Cause and Solution

400 Bad Request

POST is forbidden.

POST operations are not permitted. Check whether POST permission has been granted in API Settings.

400 Bad Request

Syntax error.

The request body is not valid JSON. Check the JSON syntax and provide it in the correct format.

400 Bad Request

Status parameter is not available in the current plan. Please upgrade your plan.

The “status” parameter is not available on your current plan. Upgrade your Plan or remove the “status” parameter.

400 Bad Request

Request body is empty.

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

Please include one or more user-defined fields.

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}' is unexpected key.

“{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

‘{fieldId}' has unexpected data type.

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’ field error. This field is valid for content that is meant to be published.

“publishedAt” can only be specified for Published Content. Remove “publishedAt” or the “status” parameter.

400 Bad Request

'{fieldId}' field error. Please fix date format.

The date format specified for “{fieldId}” is invalid. Specify it as a string in ISO format (ISO 8601).

400 Bad Request

'{fieldId}' field required error.

“{fieldId}” is required. Include it in the request body.

400 Bad Request

Please input unique value on '{fieldId}' field.

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

'{fieldId}' field invalid. The value sent does not fit the specified format.

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

'{fieldId}’ field invalid. The value sent does not meet the number of characters allowed.

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

'{fieldId}' field invalid. The value sent does not in the range.

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

'{fieldId}' field invalid. The value sent exceeds the upper or lower limit.

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

'{fieldId}' field invalid. Please set a valid URL.

The value specified for “{fieldId}” is not a valid URL. Specify the URL of an image or file uploaded to Media.

400 Bad Request

'{fieldId}' field invalid. Please set a valid file URL.

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

'{fieldId}' field invalid. Please set a valid image URL.

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

'{fieldId}' field invalid. The image width must be {width} px.

The image specified for “{fieldId}” exceeds the image size limit (width). Specify an image smaller than the configured size limit.

400 Bad Request

'{fieldId}' field invalid. Cannot use this image because its width is unknown.

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

'{fieldId}' field invalid. The image width must be {height} px.

The image specified for “{fieldId}” exceeds the image size limit (height). Specify an image smaller than the configured size limit.

400 Bad Request

'{fieldId}' field invalid. Cannot use this image because its height is unknown.

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 amount of data that can be saved has been exceeded. Please adjust the contents and try again.

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

Too many contents. Please upgrade your plan.

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.

PUT Method Error Response

Status Code

Error Message

Cause and Solution

400 Bad Request

PUT is forbidden.

The PUT operation is not permitted. Check whether the PUT permission is granted in API Key Settings.

400 Bad Request

Syntax error.

The request body is not valid JSON. Check the JSON syntax and provide it in the correct format.

400 Bad Request

Status parameter is not available in the current plan. Please upgrade your plan.

The “status” parameter cannot be specified on your current plan. Either upgrade your Plan or remove the “status” parameter.

400 Bad Request

Request body is empty.

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

contentId is necessary.

No Content ID was specified. Include the Content ID in the request URL.

400 Bad Request

Content is already exists. If you want update, please use PATCH 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

Please include one or more user-defined fields.

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

Invalid content id.

The specified Content ID contains an invalid value. Change the Content ID.

400 Bad Request

Invalid content id format.

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}' is unexpected key.

“{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

‘{fieldId}' has unexpected data type.

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’ field error. This field is valid for content that is meant to be published.

“publishedAt” can only be specified for Published Content. Remove “publishedAt” or the “status” parameter.

400 Bad Request

'{fieldId}' field error. Please fix date format.

The date format specified for “{fieldId}” is invalid. Specify it as an ISO-formatted (ISO 8601) string.

400 Bad Request

'{fieldId}' field required error.

“{fieldId}” is required. Include it in the request body.

400 Bad Request

Please input unique value on '{fieldId}' field.

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

'{fieldId}' field invalid. The value sent does not fit the specified format.

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

'{fieldId}' field invalid. The value sent does not meet the number of characters allowed.

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

'{fieldId}' field invalid. The value sent does not in the range.

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

'{fieldId}' field invalid. The value sent exceeds the upper or lower limit.

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

'{fieldId}' field invalid. Please set a valid URL.

The value specified for “{fieldId}” is not a valid URL. Specify the URL of an image or file uploaded to Media.

400 Bad Request

'{fieldId}' field invalid. Please set a valid file URL.

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

'{fieldId}' field invalid. Please set a valid image URL.

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

'{fieldId}' field invalid. The image width must be {width} px.

The image specified for “{fieldId}” exceeds the image size limit (width). Specify an image smaller than the configured size limit.

400 Bad Request

'{fieldId}' field invalid. Cannot use this image because its width is unknown.

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

'{fieldId}' field invalid. The image width must be {height} px.

The image specified for “{fieldId}” exceeds the image size limit (height). Specify an image smaller than the configured size limit.

400 Bad Request

'{fieldId}' field invalid. Cannot use this image because its height is unknown.

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 amount of data that can be saved has been exceeded. Please adjust the contents and try again.

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

Too many contents. Please upgrade your plan.

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.

Error Responses for PATCH Method

Status Code

Error Message

Cause and Solution

400 Bad Request

PATCH is forbidden.

PATCH operations are not permitted. Check whether PATCH permissions have been granted in API Key Settings.

400 Bad Request

Syntax error.

The request body is not valid JSON. Check the JSON syntax and provide it in the correct format.

400 Bad Request

Content is not exists.

The specified Content does not exist. Check that the correct Content ID is specified.

400 Bad Request

Request body is empty.

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}' is unexpected key.

“{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

‘{fieldId}' has unexpected data type.

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’ field error. This field is valid for content that is meant to be published.

“publishedAt” can only be specified for Published Content. Remove “publishedAt” from the request.

400 Bad Request

'{fieldId}' field error. Please fix date format.

The date format specified for “{fieldId}” is incorrect. Specify it as an ISO 8601 string.

400 Bad Request

Please input unique value on '{fieldId}' field.

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

'{fieldId}' field invalid. The value sent does not fit the specified format.

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

'{fieldId}’ field invalid. The value sent does not meet the number of characters allowed.

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

'{fieldId}' field invalid. The value sent does not in the range.

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

'{fieldId}' field invalid. The value sent exceeds the upper or lower limit.

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

'{fieldId}' field invalid. Please set a valid URL.

The value specified for “{fieldId}” is not a valid URL. Specify the URL of an image or file uploaded to Media.

400 Bad Request

'{fieldId}' field invalid. Please set a valid file URL.

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

'{fieldId}' field invalid. Please set a valid image URL.

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

'{fieldId}' field invalid. The image width must be {width} px.

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

'{fieldId}' field invalid. Cannot use this image because its width is unknown.

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

'{fieldId}' field invalid. The image width must be {height} px.

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

'{fieldId}' field invalid. Cannot use this image because its height is unknown.

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 amount of data that can be saved has been exceeded. Please adjust the contents and try again.

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 cannot be changed because it is closed.

The status of Content whose publication has ended cannot be updated via the API. Update it from the Administration console.

DELETE Method Error Response

Status Code

Error Message

Cause and Solution

400 Bad Request

DELETE is forbidden.

The DELETE operation is not permitted. Check whether the DELETE permission is granted in API Settings.

400 Bad Request

Content is not exists.

The specified Content does not exist. Check that the correct Content ID is specified.

400 Bad Request

The content is referenced."

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.

Contents

  • Response Body on Error
  • List of Error Responses
  • Common Error Responses for All Methods
  • GET Method Error Response
  • Error Responses for POST Method
  • PUT Method Error Response
  • Error Responses for PATCH Method
  • DELETE Method Error Response
  • Company
  • Legal Notice
  • Terms of Service
  • Privacy Policy

Copyright © microcms.io All rights reserved.