Travis CI API Docs

Error handling

Note that in these examples, we omit authentication. Some JSON responses are also abbreviated.

Clients can read the home document to obtain a list of possible errors, including their HTTP status codes and possible additional attributes.

curl -H "Travis-API-Version: 3" https://api.travis-ci.com/

{
  "@type":  "home",
  "@href":  "/",
  "errors": {
    "login_required":     {
      "status":                403,
      "default_message":       "login required",
      "additional_attributes": [ ]
    },
    "method_not_allowed": {
      "status":                405,
      "default_message":       "method not allowed",
      "additional_attributes": [ ]
    },
    "not_found":          {
      "status":                404,
      "default_message":       "resource not found (or insufficient access)",
      "additional_attributes": [
        "resource_type"
      ]
    }
  }
}

The identifiers, such as not_found, represent potential values of the error_type field in error response bodies. See the following example.

curl -H "Travis-API-Version: 3" https://api.travis-ci.com/repo/1000000000

{
  "@type":         "error",
  "error_type":    "not_found",
  "error_message": "repository not found (or insufficient access)",
  "resource_type": "repository"
}

Understanding errors

Error responses are as descriptive as possible, and sometimes contain extra fields to help clients understand why the error occurred.

Imagine we are permitted to read a user setting for a repository, but not to change it. We can confirm this by checking the @permissions metadata for the resource.

curl -H "Travis-API-Version: 3" \
  https://api.travis-ci.com/repo/999/setting/build_pushes

{
  "@type":           "setting",
  "@href":           "/repo/999/setting/build_pushes",
  "@representation": "standard",
  "@permissions":    {
    "read":          true,
    "write":         false
  },
  "name":            "build_pushes",
  "value":           true
}

We can see that the write permission is false. A PATCH request to update the setting would then result in the following error.

curl -X PATCH \
   -H "Travis-API-Version: 3" \
   -d '{"setting.value":false}' \
   https://api.travis-ci.com/repo/999/setting/build_pushes

{
  "@type":         "error",
  "error_type":    "insufficient_access",
  "error_message": "operation requires write access to user_setting",
  "permission":    "write",
  "resource_type": "user_setting",
  "user_setting":  {
    "@type":           "user_setting",
    "@href":           "/repo/999/setting/build_pushes",
    "@representation": "minimal",
    "name":            "build_pushes",
    "value":           true
  }
}

The permission field is included in the response, along with a minimal representation of the relevant resource.