Skip to main content
Plane uses standard HTTP response codes to indicate the success or failure of an API request. Codes in the 2xx range indicate success. Codes in the 4xx range indicate an error that failed given the information provided. Codes in the 5xx range indicate an error with Plane’s servers. Most errors will include an error code that can be used to handle the issue programmatically, and explain the problem reported.

​
Attributes

​
string
A short string indicating the error code reported.
​
string
A human-readable message providing more details about the error.
​
object
An object with key-value pairs that may provide more details about the error. For example, a parameter validation error will have the list of parameters that are invalid with reasons. In some cases, details may be an empty object.
For workers, policies, departments, attributes, records, and object types, permission errors return 403 unauthorized, missing resources return 404 not_found, and validation errors return 422 invalid. Validation errors can include field-specific details alongside reasons.

​
Reasons

error.reasons is an optional array explaining why the request was refused. Every item has code and message. It may include subject, the plain ID of the resource concerned, and param, a dotted input path such as items.0.amount, not a JSON Pointer. Optional fields are omitted when unavailable. Clients must ignore unknown members on error and each reason. message states the primary problem; reasons provides the individual explanations.

​
Authority and prerequisites

An access error may prevent other requirements from being evaluated. After resolving the reported problem, retry the request to check for any remaining requirements. feature.inactive means the feature is not enabled for the workspace. Permission to enable a feature does not mean it is already enabled.

​
MCP errors

MCP errors include the application code, message, and optional reasons within the MCP error response. When an action is unavailable in the resource’s current status, the message names that status.

​
Error codes

Below is a list of error codes that Plane may return in the code field, along with information on how to resolve them.

​
Payment and charge eligibility

Payment creation returns HTTP 422 with error.code: "invalid" when the sending entity is not verified, its payments capability is unavailable, or the recipient cannot be paid. Reasons identify the domain condition, such as entity.unverified or recipient.unavailable. An unavailable capability is reported as capability.unavailable; this may appear alongside unmet domain conditions. A capability precheck can refuse the action before those conditions are evaluated. Charge creation and payment-request payment return 422 invalid when funding requirements are not met. Reasons distinguish source.required from source.unavailable. Cancelling an ineligible payment returns 422 invalid with the reason payment.not_cancellable. Access errors return 403 unauthorized.