{"action":"created","issue":{"url":"https://api.github.com/repos/zalando/restful-api-guidelines/issues/42","repository_url":"https://api.github.com/repos/zalando/restful-api-guidelines","labels_url":"https://api.github.com/repos/zalando/restful-api-guidelines/issues/42/labels{/name}","comments_url":"https://api.github.com/repos/zalando/restful-api-guidelines/issues/42/comments","events_url":"https://api.github.com/repos/zalando/restful-api-guidelines/issues/42/events","html_url":"https://github.com/zalando/restful-api-guidelines/issues/42","id":151174518,"number":42,"title":"Don't specify all possible HTTP errors","user":{"login":"ePaul","id":645859,"avatar_url":"https://avatars.githubusercontent.com/u/645859?v=3","gravatar_id":"","url":"https://api.github.com/users/ePaul","html_url":"https://github.com/ePaul","followers_url":"https://api.github.com/users/ePaul/followers","following_url":"https://api.github.com/users/ePaul/following{/other_user}","gists_url":"https://api.github.com/users/ePaul/gists{/gist_id}","starred_url":"https://api.github.com/users/ePaul/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/ePaul/subscriptions","organizations_url":"https://api.github.com/users/ePaul/orgs","repos_url":"https://api.github.com/users/ePaul/repos","events_url":"https://api.github.com/users/ePaul/events{/privacy}","received_events_url":"https://api.github.com/users/ePaul/received_events","type":"User","site_admin":false},"labels":[{"url":"https://api.github.com/repos/zalando/restful-api-guidelines/labels/discussion","name":"discussion","color":"cc317c"},{"url":"https://api.github.com/repos/zalando/restful-api-guidelines/labels/guideline-change","name":"guideline-change","color":"5319e7"}],"state":"open","locked":false,"assignee":{"login":"whiskeysierra","id":429981,"avatar_url":"https://avatars.githubusercontent.com/u/429981?v=3","gravatar_id":"","url":"https://api.github.com/users/whiskeysierra","html_url":"https://github.com/whiskeysierra","followers_url":"https://api.github.com/users/whiskeysierra/followers","following_url":"https://api.github.com/users/whiskeysierra/following{/other_user}","gists_url":"https://api.github.com/users/whiskeysierra/gists{/gist_id}","starred_url":"https://api.github.com/users/whiskeysierra/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/whiskeysierra/subscriptions","organizations_url":"https://api.github.com/users/whiskeysierra/orgs","repos_url":"https://api.github.com/users/whiskeysierra/repos","events_url":"https://api.github.com/users/whiskeysierra/events{/privacy}","received_events_url":"https://api.github.com/users/whiskeysierra/received_events","type":"User","site_admin":false},"milestone":null,"comments":3,"created_at":"2016-04-26T16:04:04Z","updated_at":"2016-04-27T18:02:07Z","closed_at":null,"body":"The guidelines currently say (in section \"HTTP\", rule \"[Must: Providing Error Documentation](http://zalando.github.io/restful-api-guidelines/http/Http.html#must-providing-error-documentation)\"):\r\n\r\n> The OpenAPI specification shall include definition of all error status codes and error descriptions\r\n> that possibly will be returned; they are part of the interface definition and provide important\r\n> information for service clients to handle exceptional situations and support troubleshooting.\r\n\r\nI think we should instead encourage to not document common HTTP errors which have no special meaning for this API, but just the default HTTP meaning, and can happen always (like 500, 503, ...).\r\n\r\nClients should be prepared for unexpected response codes, and in case of doubt handle them like they would handle the corresponding x00 code. Adding new response codes (specially error responses) should be considered a compatible API evolution.\r\n\r\n(This might also affect the compatibility section.)"},"comment":{"url":"https://api.github.com/repos/zalando/restful-api-guidelines/issues/comments/215173176","html_url":"https://github.com/zalando/restful-api-guidelines/issues/42#issuecomment-215173176","issue_url":"https://api.github.com/repos/zalando/restful-api-guidelines/issues/42","id":215173176,"user":{"login":"ePaul","id":645859,"avatar_url":"https://avatars.githubusercontent.com/u/645859?v=3","gravatar_id":"","url":"https://api.github.com/users/ePaul","html_url":"https://github.com/ePaul","followers_url":"https://api.github.com/users/ePaul/followers","following_url":"https://api.github.com/users/ePaul/following{/other_user}","gists_url":"https://api.github.com/users/ePaul/gists{/gist_id}","starred_url":"https://api.github.com/users/ePaul/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/ePaul/subscriptions","organizations_url":"https://api.github.com/users/ePaul/orgs","repos_url":"https://api.github.com/users/ePaul/repos","events_url":"https://api.github.com/users/ePaul/events{/privacy}","received_events_url":"https://api.github.com/users/ePaul/received_events","type":"User","site_admin":false},"created_at":"2016-04-27T18:02:07Z","updated_at":"2016-04-27T18:02:07Z","body":"@tfrauenstein I'm not sure how to distinguish \"error codes that are not yet returned\" from \"error codes that are returned\" in an API first setting (i.e. before any implementation is there).\r\n\r\nWhat triggered this issue was the question whether we (as API designers) need to add a '500' (internal Server error) and '503' (temporary not available) response for all operations, because one can never be certain that these don't happen, or if we can simply omit them from the description, and expect the client to handle them anyways."}}