Errors

The Files.com API returns standard HTTP success (2xx) or error (4xx, 5xx) status codes. Status codes in the 5xx range are unexpected and indicate an error occurred with our API. Wait some time and then try again. If you get a 500 repeatedly, it may be a bug. Please report it.

Note that success codes can include 200, 201, and 204.

The Files.com API returns errors in a standard structure for both JSON and XML API requests as well as our SDKs. Because different types of errors will share the same HTTP response code, it is strongly recommended to use the type attribute of the returned error object and not the HTTP response code when handling errors.

When the request encounters an error while creating or updating a record, the response will include three additional JSON objects: errors, model_errors, and model_error_keys. The errors object contains user friendly error strings translated into your site's default language. The model_errors object contains the user friendly error strings from the errors object mapped to the parameter that caused the error. The model_error_keys object contains the translation keys used to generate the user friendly entries in model_errors. These keys can be used for language independent error handling logic. For errors which do not have translation keys, the model_error_keys entries will instead contain the English error string.

Each SDK implements exception handling in a native way using these error types. You can catch/rescue individual error types as well as error type families.

Example Responses

{
   "error":"Unauthorized. The API key or Session token is either missing or invalid.",
   "http-code":401,
   "instance":"a69f6b06-6ba9-4e71-8542-60d2ff3d96f2",
   "title":"Authentication Required",
   "type":"not-authorized/authentication-required"
}

{
   "error":"Invalid username or password",
   "http-code":401,
   "instance":"d895ebaa-7e7e-4ced-87c9-2acf743a19c3",
   "title":"Invalid Username Or Password",
   "type":"bad-request/invalid-username-or-password"
}

{
   "error":"You do not have read permission for this path, file.txt",
   "http-code":403,
   "instance":"37ffdbfb-8faa-4af9-8091-29162f0be67c",
   "title":"Read Permission Required",
   "type":"not-authorized/read-permission-required"
}

{
  "error": "Error saving model.",
  "http-code": 422,
  "instance": "508503b0-2423-4edc-a46f-77d77ac4a7e3",
  "model_errors": {
    "username": [
      "Username must not contain multiple spaces together",
      "Username must not begin or end with a space"
    ]
  },
  "model_error_keys": {
    "username": [
      "multiple_spaces",
      "leading_trailing_space"
    ]
  },
  "errors": [
    "Username must not contain multiple spaces together",
    "Username must not begin or end with a space"
  ],
  "title": "Model Save Error",
  "type": "processing-failure/model-save-error"
}