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
  • Management API (Beta)

Management API Error Responses

Last updated: 2026/11/19

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

Caution

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 When an Error Occurs

Management API error responses may include a message like the following in the response body.

{
    message: "some message"
}
Caution

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

List of Error Responses

Common Error Responses

Status Code

Error Message

Cause and Solution

400 Bad Request

IP address rejected.

The request is coming from an unauthorized IP address. Please check the API IP restriction settings and make the request from an allowed IP address.

403 Forbidden

Forbidden

Operations via the Management API are not permitted. Please check if the API key is correctly set and if permissions are granted in the API key settings.

404 Not Found

Not Found

The requested URL is incorrect. Please check for any typos in the URL.

429 Too Many Requests

Too Many Requests

You have exceeded the API call limit.

500 Internal Server Error

Internal Server Error

An unexpected error has occurred on the server side.

Error Responses for Content Operations

GET Method

Status Code

Error Message

Cause and Solution

400 Bad Request

Limit: must be no less than 0.

A value less than 0 was specified for the limit parameter. Specify a number between 0 and 100, inclusive.

400 Bad Request

limit must be less than or equal to 100

A value greater than 100 was specified for the limit parameter. Specify a number between 0 and 100, inclusive.

400 Bad Request

Invalid integer in query (limit=xxx)

An invalid value was specified for the limit parameter. Specify a number between 0 and 100, inclusive.

400 Bad Request

Offset: must be no less than 0

A value less than 0 was specified for the offset parameter. Specify a number greater than or equal to 0.

400 Bad Request

Invalid integer in query (offset=xxx)

An invalid value was specified for the offset parameter. Specify a number greater than or equal to 0.

404 Not Found

Content not found

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

PUT Method

Status Code

Error Message

Cause and Solution

400 Bad Request

invalid request body

An invalid value is specified in the body. Please check the content of the body.

400 Bad Request

Past dates and times cannot be set as the reserved open date and time

A past date and time has been specified for the scheduled publication. Please specify a future value relative to the current time.

400 Bad Request

Past date and time cannot be set as the date and time to stop publishing reservations

A past date and time has been specified for the scheduled end of publication. Please specify a future value relative to the current time.

400 Bad Request

Cannot set publish or close schedule while under review

You are trying to set a reservation for content that is under review. Please complete or withdraw the review before setting the reservation.

400 Bad Request

Cannot be reserved for the public because it has already been published

You are specifying a reservation to start publication for content that is already published. Please set a reservation to end publication first, or remove the reservation to start publication from the body.

400 Bad Request

Reservations to start publishing must be set after reservations to stop publishing if the content is being published

If the content is currently published, the reservation to start publication must be set after the reservation to stop publication. Please specify the end reservation first and the start reservation later.

400 Bad Request

Cannot be reserved to stop publication while drafting

You are specifying only a reservation to end publication for draft content. Please also set a reservation to start publication, or remove the reservation to end publication from the body.

400 Bad Request

Reservations to stop publishing must be set after reservations to start publishing if content is in draft

The reservation to end publication for draft content must be set after the reservation to start publication. Please specify the start reservation first and the end reservation later.

400 Bad Request

Cannot be reserved to stop publication if the content is closed to the public

You are specifying only a reservation to end publication for content that is closed to the public. Please also set a reservation to start publication, or remove the reservation to end publication from the body.

400 Bad Request

Reservations to stop publishing must be set after reservations to start publishing if the content is closed to the public

The order of the start/end reservations specified for closed content is incorrect. Please set the start reservation first and the end reservation later.

PATCH Method

Status Code

Error Message

Cause and Solution

400 Bad Request

Status: (0: must be a valid value.).

An invalid value is specified in the body. Please check the content of the body.

400 Bad Request

Status: the length must be exactly 1.

An invalid value is specified in the body. Please check the content of the body.

400 Bad Request

invalid user id

An invalid user ID is specified in the body. Please specify an existing user ID.

400 Bad Request

Request body is not JSON object.

The JSON format specified in the body is incorrect. Please check the content of the body.

405 Method Not Allowed

Method Not Allowed

This is a request with a method that is not allowed. Please check if the URL is correct.

Media Operation Error Response

GET Method

Status Code

Error Message

Cause and Solution

400 Bad Request

Limit: must be no less than 0.

A value less than 0 was specified for the limit parameter. Specify a number between 0 and 100, inclusive.

400 Bad Request

limit must be less than or equal to 100

A value greater than 100 was specified for the limit parameter. Specify a number between 0 and 100, inclusive.

400 Bad Request

Invalid integer in query (limit=xxx)

An invalid value was specified for the limit parameter. Specify a number between 0 and 100, inclusive.

400 Bad Request

Invalid boolean in query (imageOnly=xxx)

An invalid value was specified for the imageOnly parameter. Specify either true or false.

400 Bad Request

Offset: must be no less than 0

An invalid value was specified for the offset parameter. Specify a number greater than or equal to 0.

400 Bad Request

Invalid integer in query (offset=xxx)

An invalid value was specified for the offset parameter. Specify a number greater than or equal to 0.

400 Bad Request

BadRequest

The value of the token parameter is invalid, or the token is invalid.

404 Not Found

Content not found

No media item with the specified string as its file name exists for the fileName parameter.

POST Method

Status Code

Error Message

Cause and Solution

400 Bad Request

invalid request

The format of the request is invalid. Please check the contents of the request body.

400 Bad Request

request body too large

The file size of the media being uploaded exceeds 5MB. Please reduce the size or upload it from the Administration console.

405 Method Not Allowed

Method Not Allowed

This is a request with an unsupported method. Please check if the URL is correct.

DELETE Method

Status Code

Error Message

Cause and Solution

400 Bad Request

invalid url

The specified URL is invalid. Please check if the URL is correct.

400 Bad Request

this medium is referenced by another content

It cannot be deleted because it is referenced by another content. Please remove the reference to the media from the source content.

404 Not Found

medium not found

The media to be deleted does not exist. Please check if the correct media URL is specified.

405 Method Not Allowed

Method Not Allowed

This is a request with an unsupported method. Please check if the URL is correct.

Member Operation Error Response

GET Method

Status Code

Error Message

Cause and Solution

404 Not Found

Member not found

The member you are trying to retrieve does not exist or is still pending invitation. Please specify a member who has already joined the service.

PATCH Method

Status Code

Error Message

Cause and Solution

400 Bad Request

Examples:

  • "roleIds" is required
  • "roleIds" must not be null
  • "roleIds" must be of type array

The request body is invalid. Check that roleIds is specified, that its value is an array and not null, and that it does not contain any undefined properties.

400 Bad Request

Invalid member id

The member ID is invalid. Specify a member ID included in the response from the API for retrieving the member list.

400 Bad Request

Examples:

  • "roleIds" must not be empty
  • "roleIds[1]" is duplicated
  • "roleIds[0]" is not a valid role id

roleIds contains an empty array, duplicate role IDs, or role IDs in an invalid format. Specify one or more unique role IDs in roleIds, using IDs included in the response from the API for retrieving the role list.

400 Bad Request

Example:
"roleIds[0]" does not exist

The specified role does not exist in the target Service. Check that the role belongs to the correct Service and that the specified role ID is correct.

403 Forbidden

Forbidden

Member roles cannot be updated in environments created using the Multiple Environments feature. Check the Service ID in the request URL.

404 Not Found

Member not found

The specified member does not exist in the Service. Use the API for retrieving the member list to check whether the specified member ID exists in the target Service.

409 Conflict

Roles of inviting members cannot be updated

The specified member has been invited but has not yet joined. Retry the request after the member has joined the Service.

409 Conflict

At least one administrator is required

After the update, no joined members in the Service will have the administrator role. Check the role IDs specified in roleIds to ensure that at least one joined member retains the administrator role. Invited members are not counted as administrators.

413 Payload Too Large

Request Entity Too Large

The request body exceeds 1 MiB. Adjust the request body so that it is no larger than 1 MiB.

API Operation Error Responses

GET Method

Status Code

Error Message

Cause and Solution

400 Bad Request

Endpoint: must be in a valid format.

The Endpoint format is invalid. Check that the specified Endpoint is correct.

POST Method

Status Code

Error Message

Cause and Solution

400 Bad Request

Examples:

  • "name" must be of type string
  • field "num": "isUnique" is not a valid property for kind "number"

The request body is invalid. Check that all required fields are specified, that values have the correct types, and that the request does not contain undefined properties or properties that are not supported for the specified field type.

400 Bad Request

Examples:

  • field "title": "initialValue" must be of type string
  • initialValue length must be at most 100 characters

The type of initialValue does not match the field type, or it does not meet the configured validation criteria. Specify a type supported by the field type, and check the constraints for character count, regular expressions, numeric ranges, and so on.

400 Bad Request

Example:
richEditorV2Options contains invalid value "undo"

richEditorV2Options contains fixed options that cannot be specified (undo, redo, and clean). These options are always enabled, so remove them from the specification.

400 Bad Request

Examples:

  • customFieldId "block" does not match any customFields entry
  • customFieldIds entry "block" does not match any customFields entry

customFieldId or customFieldIds specifies a Field ID that is not defined in customFields. Specify a Field ID defined in customFields in the same request.

400 Bad Request

Invalid boolean in query (allowAdditionalCharge=xxx)

An invalid value is specified for the allowAdditionalCharge parameter. Specify true or false.

402 Payment Required

API count has been exceeded. Set allowAdditionalCharge to true to allow additional charges.

On the Team plan, Business plan, or Enterprise plan, you are trying to create an API that exceeds the API limit without specifying allowAdditionalCharge=true. To allow additional charges, specify allowAdditionalCharge=true.

403 Forbidden

APIs count has been exceeded

On the Hobby plan or Template plan, you are trying to create an API that exceeds the API limit. These plans do not allow you to exceed the limit, regardless of the value specified for allowAdditionalCharge. Check your Plan or API count.

403 Forbidden

File fields are not available on your current plan

A File Field that is not available on your current Plan is specified. Check whether the request body contains a File Field and whether it is available on your Plan.

409 Conflict

Example:
Endpoint "news" is already in use

An API using the specified Endpoint already exists. Specify an Endpoint that is unique within the Service.

413 Payload Too Large

Request Entity Too Large

The request body exceeds 1 MiB. Adjust the request body so that it is no larger than 1 MiB.

Error Responses for Role Operations

GET Method

Status Code

Error Message

Cause and Solution

400 Bad Request

limit must be less than or equal to 100

A value greater than 100 was specified for the limit parameter. Specify an integer less than or equal to 100.

400 Bad Request

Invalid integer in query (limit=xxx)

An invalid value was specified for the limit parameter. Specify an integer.

400 Bad Request

Invalid token parameter

An invalid value was specified for the token parameter. Specify the token value included in the previous response.

400 Bad Request

Invalid paging token

The contents of the token parameter are invalid. Specify the token value included in the previous response when making a request to the same Service.

400 Bad Request

Invalid role id

The role ID format is invalid. Specify a UUID-formatted value using lowercase letters for role_id.

403 Forbidden

Forbidden

Roles cannot be retrieved in environments created using the Multiple Environments feature. Check the Service ID of the target service.

404 Not Found

Role not found

The role to retrieve does not exist. Check that the specified role ID is correct.

POST Method

Status Code

Error Message

Cause and Solution

400 Bad Request

Examples:

  • "name" is required
  • "name" must be between 1 and 100 characters

The request body is invalid. Check that all required fields are specified, that values are of the correct type and not null, and that no undefined properties are included. Also check that the value specified for level is valid and that name contains between 1 and 100 characters.

400 Bad Request

Example:

"permissions.individualPermissions[0].apiId" does not exist

A member, environment, or API that does not exist or cannot be specified was provided. Check that the request does not include members who have been invited or members or environments from another Service, and verify that the specified API ID is correct.

403 Forbidden

Current plan does not allow adding roles

Your current Plan does not support the Role feature. Check which Plans support the Role feature (Business and Enterprise).

403 Forbidden

Forbidden

Roles cannot be created in environments created using the Multiple Environments feature. Check the Service ID specified in the request.

413 Payload Too Large

Request Entity Too Large

The request body exceeds 1 MiB. Adjust the request body so that it is no larger than 1 MiB.

PATCH Method

Status Code

Error Message

Cause and Resolution

400 Bad Request

Invalid role id

The role ID format is invalid. Specify a UUID-formatted value using lowercase letters for role_id.

400 Bad Request

Either "name" or "permissions" is required

Neither name nor permissions is specified. Specify at least one of them.

400 Bad Request

Examples:

  • "permissions.individualPermissions" is required
  • "permissions.defaultPermissions" is required

The request body is invalid. If you specify permissions, you must specify both defaultPermissions and individualPermissions. Also check that all required fields are specified, that values have the correct types and are not null, that no undefined properties are included, and that the value specified for level is valid.

400 Bad Request

Example:

"permissions.individualPermissions[0].apiId" does not exist

A member, environment, or API that does not exist or cannot be specified was provided. Check that the request does not include invited members or members or environments from another Service, and verify that the specified API ID is correct.

403 Forbidden

Administrator role cannot be edited

The Administrator role was specified. The Administrator role cannot be updated. Check the role ID of the role you want to update.

403 Forbidden

Forbidden

Roles cannot be updated in environments created using the Multiple Environments feature. Check the Service ID in the request destination.

404 Not Found

Role not found

The role to be updated does not exist in the Service. Check that the specified role ID is correct.

413 Payload Too Large

Request Entity Too Large

The request body exceeds 1 MiB. Adjust the request body so that it is no larger than 1 MiB.

DELETE Method

Status Code

Error Message

Cause and Solution

400 Bad Request

Invalid role id

The role ID format is invalid. Specify a UUID-formatted value using lowercase letters for role_id.

403 Forbidden

Administrator role cannot be edited

The Administrator role was specified. The Administrator role cannot be deleted. Check the role ID to be deleted.

403 Forbidden

Forbidden

Roles cannot be deleted in environments created using the Multiple Environments feature. Check the Service ID in the request destination.

404 Not Found

Role not found

The role to be deleted does not exist in the Service. Check that the specified role ID is correct.

409 Conflict

Remove roles from all members

The role to be deleted is assigned to one or more members, including members who have been invited. Remove the role from all members to whom it is assigned, including invited members, and then submit the request again.

Contents

  • Response Body When an Error Occurs
  • List of Error Responses
  • Common Error Responses
  • Error Responses for Content Operations
  • Media Operation Error Response
  • Member Operation Error Response
  • API Operation Error Responses
  • Error Responses for Role Operations
  • Company
  • Legal Notice
  • Terms of Service
  • Privacy Policy

Copyright © microcms.io All rights reserved.