Error Handling

Expected errors that occur when interacting with the API result in a 4xx error code, which varies depending on the condition. All error responses contain at least a detail attribute explaining why the error occurred. The following is a list of some of the most common errors that are encountered and why:

Not Authenticated

A 401 Unauthorized status code is sent when the resource endpoint expects the user to be authenticated but the user isn't. For example, if sending a request as an anonymous user to an authenticated endpoint the following error is sent as a response:

HTTP/1.0 401 Unauthorized
Allow: POST, OPTIONS
Content-Length: 58
Server: Cloudsmith MCP

{
  "detail": "Authentication credentials were not provided."
}

No Permissions

A 403 Forbidden status code is sent when the resource endpoint expects the user to have specific permissions, which will be detailed in the resource endpoint documentation. For example, if sending a request as an authenticated user to a resource endpoint in which we don't have permissions (such as one belonging to another user), the following error is sent as a response:

HTTP/1.0 401 Unauthorized
Allow: POST, OPTIONS
Content-Length: 63
Server: Cloudsmith MCP

{
  "detail": "You do not have permission to perform this action."
}

🚧

Variable Messages

The detail field in response can be customised by the resource endpoint, so it might be different than the text shown above.

Invalid JSON Object Error

A 400 Bad Request status code is sent when the body of the document is expected to be JSON encoded, but the actual content is otherwise. For example, if the body was sent as foo then the following error is sent as a response:

HTTP/1.0 400 Bad Request
Allow: POST, OPTIONS
Content-Length: 68
Content-Type: application/json
Server: Cloudsmith MCP

{
  "detail": "JSON parse error - No JSON object could be decoded"
}

Malformed JSON Error

A 400 Bad Request status code is sent when the body of the document is cannot be parsed as syntactically correct JSON. For example, if the body was sent as { then the following error is sent as a response:

HTTP/1.0 400 Bad Request
Content-Length: 79
Content-Type: application/json
Server: Cloudsmith MCP

{
  "detail": "JSON parse error - Expecting object: line 1 column 1 (char 0)"
}

Field Validation Error

A 422 Unprocess Entity status code is sent when the resource endpoint receives a JSON body that is syntactically but not semantically correct. These error responses contain a fields attribute that lists the specific fields affected by the error condition. For example, if the resource endpoint expected a filename attribute in the body to be populated but isn't then the following error is sent as a response:

HTTP/1.0 422 Unprocessable Entity
Content-Length: 132
Content-Type: application/json
Server: Cloudsmith MCP

{
  "fields": {
    "filename": [
      "This field may not be null."
    ]
  },
  "code": "invalid",
  "detail": "Invalid input."
}