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/
{ "": "home", "": "/", "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
{ "": "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
{ "": "setting", "": "/repo/999/setting/build_pushes", "": "standard", "": { "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
{ "": "error", "error_type": "insufficient_access", "error_message": "operation requires write access to user_setting", "permission": "write", "resource_type": "user_setting", "user_setting": { "": "user_setting", "": "/repo/999/setting/build_pushes", "": "minimal", "name": "build_pushes", "value": true } }
The permission
field is included in the response, along with a minimal
representation of the relevant resource.