API Error Response

Overview

This document summarizes the error codes returned in an API error response, and the list of validation errors that can be set in content definitions. Each response includes the following fields: code, message, and field.

• code: A string representing the error type code (e.g., invalid for invalid request parameters)
• message: Standard error message for Kuroco
• field: The request parameter where the error occurred; not outputted for general errors

List of Error Codes

The codes that appear in errors[].code fall into two groups: those that describe the outcome of the request as a whole, and those that describe the content of an individual field.

Request-level errors

Returned when processing of the request itself failed. These map one-to-one to the HTTP status.

Code	HTTP Status	Description
bad_request	400	The content of the request is invalid.
unauthorized	401	Not authenticated.
forbidden	403	The permission required for the operation is missing.
not_found	404	The target data does not exist.
method_not_allowed	405	That HTTP method is not allowed.
not_acceptable	406	The specified output format is not supported.
request_timeout	408	The request timed out.
payload_too_large	413	The size of the uploaded file exceeds the limit.
unprocessable_entity	422	The request is well-formed but its content cannot be processed.
internal_server_error	500	An error occurred inside the server.

An error that falls into none of the above is returned as undefined.

Field-level errors

Returned when a submitted value does not meet the input conditions. The target field is set in field.

Code	Description
required	A required field was not filled in.
invalid	The value of the field does not meet the input conditions.

note

Field-level errors do not map one-to-one to the HTTP status. For validation errors set in a content definition, the HTTP status is 400 and code is either required or invalid. See List of Validation Errors for the specific conditions and messages.

List of Validation Errors

note

This section contains validation errors set in content definitions. If there is a problem with the request, a different error will occur.

Common

Condition	HTTP Status	Code	Message
Required Check	400	required	[item name] is required

Title

Condition	HTTP Status	Code	Field	Message
Input Restriction (E-mail)	400	invalid	subject	Invalid Text Please enter in a E-mail format.
Input Restriction (Phone Number)	400	invalid	subject	Invalid Text Please enter in a Contact number format.
Input Restriction (Postal Code)	400	invalid	subject	Invalid Text Please enter in a ZIP code format.
Input Restriction (URL)	400	invalid	subject	Invalid Title. Please enter in a URL format.
Input Restriction (Number)	400	invalid	subject	Invalid Title. Please enter in a Numeric value format.
Input Restriction (Regular Expression)	400	invalid	subject	Invalid Title
Input Restriction (Minimum Character Count)	400	invalid	subject	Title should be X characters or more.
Input Restriction (Maximum Character Count)	400	invalid	subject	Please input Title within X characters.

Single-line text

Condition	HTTP Status	Code	Field	Message
Input Restriction (E-mail)	400	invalid	ext_x	Invalid [item name]. Please enter in a E-mail format.
Input Restriction (Phone Number)	400	invalid	ext_x	Invalid [item name]. Please enter in a Contact number format.
Input Restriction (Postal Code)	400	invalid	ext_x	Invalid [item name]. Please enter in a ZIP code format.
Input Restriction (URL)	400	invalid	ext_x	Invalid [item name]. Please enter in a URL format.
Input Restriction (Number)	400	invalid	ext_x	Invalid [item name]. Please enter in a Numeric value format.
Input Restriction (Regular Expression)	400	invalid	ext_x	Invalid [item name]
Input Restriction (Minimum Character Count)	400	invalid	ext_x	Invalid The Number of characters of [item name]
Input Restriction (Maximum Character Count)	400	invalid	ext_x	Invalid The Number of characters of [item name]

Multi-line text

Condition	HTTP Status	Code	Field	Message
Input Restriction (Minimum Character Count)	400	invalid	ext_x	Invalid The Number of characters of [item name]
Input Restriction (Maximum Character Count)	400	invalid	ext_x	Invalid The Number of characters of [item name]

Image (uploaded to KurocoFiles)

Condition	HTTP Status	Code	Field	Message
Input restriction (file extension)	400	invalid	ext_x	Invalid [item name] [File name]
Input restriction (file size limit)	400	invalid	ext_x	[Item name] Could not upload: the file size is too big

File (uploaded to KurocoFiles)

Condition	HTTP Status	Code	Field	Message
Input restriction (file extension)	400	invalid	ext_x	Invalid [item name] [File name]
Input restriction (file size limit)	400	invalid	ext_x	[Item name] Could not upload: the file size is too big

File (uploaded to GCS)

Condition	HTTP Status	Code	Field	Message
Input restriction (file extension)	400	invalid	ext_x	Invalid [item name] [File name]

File (uploaded to S3)

Condition	HTTP Status	Code	Field	Message
Input restriction (file extension)	400	invalid	ext_x	Invalid [item name] [File name]

Error Response Sample

The error response sample for when the subject is empty or not specified in the content addition API is as follows:

{
  "errors": [
    {
      "code": "invalid",
      "message": "Title is required.",
      "field": "subject"
    }
  ],
  "x-rcms-request-id": "280496b2-8b45-4a9a-8a21-678feb77e2ff"
}

• If the error is specific to a certain field, the field will contain the name of the target field.

Warning response (warnings)

Write-type APIs that run admin panel functions via the API, such as adding or updating content, may return messages and warnings in addition to errors.

Key	Meaning
errors	The operation failed. Nothing was written.
messages	Notice that the operation succeeded (e.g. "Updated").
warnings	Notice that the write succeeded but part of it was not applied, or that an operation was not allowed by permissions. Included in the response only when there is such a notice.

warnings is an array of strings. The HTTP status stays that of a successful request (200) and errors is empty, so a client that checks only errors will not notice that part of the write was not applied. When using write-type APIs, check warnings even on success.

Examples of notices included in warnings:

• A member of a group that is not allowed sent a value for a field that has Edit restriction configured in the field settings of the content structure. The field keeps its saved value and only the other fields are updated.
• Rows were skipped during CSV / JSON import
• Approval requests that were counted as "already requested" or "skipped because there are no changes"

The sample response for updating content that includes a field subject to Edit restriction is as follows:

{
  "errors": [],
  "messages": [
    "Updated"
  ],
  "warnings": [
    "The following fields were not updated because of the edit restriction: ext_1"
  ],
  "id": 1,
  "x-rcms-request-id": "280496b2-8b45-4a9a-8a21-678feb77e2ff"
}

Related documents

• Content structure
• List of extension items available in the content structure
• Where can I find a list of API error messages?
• What should I do if the API is not working?
• What should I do in case of errors?