Skip to content

RFC: Standardize API error messages #48

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
taylorsilva wants to merge 2 commits into from
Closed

RFC: Standardize API error messages #48

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
daeb339
RFC #48 Standardize API error messages
aoldershaw Apr 14, 2020
5b8fe37
Add open question
taylorsilva Apr 14, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
49 changes: 49 additions & 0 deletions 048-standard-error-messages/proposal.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,49 @@
# Summary

This RFC proposes that the Concourse API standardize on returning human and
machine readable error messages.

Authors: @taylorsilva @aoldershaw

# Motivation

As a consumer of the Concourse API (e.g. `fly`) I want to return a helpful error
messages to my end-user. This proves to be difficult to do because all I can do
is imprecisely reason about why an error occured based on the HTTP status code
returned by the API.

Example: The API endpoint for getting a pipeline config may return HTTP 404 in
two situations: 1) the config is not found and 2) the pipeline is archived. It's
currently not possible without further introspecition to distinguish between
these two cases at the client level.


# Proposal

When the Concourse API returns an error (4xx and 5xx status codes) it should

@chenbh chenbh May 10, 2021

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should we differentiate between different levels of verbosity for 4xx vs 5xx codes? 4xx codes usually indicate user error and misuse of the API, in which case a helpful error message would be appreciated. 5xx codes indicate something has gone wrong on the server side and there's nothing the user can really do with the error message.

return the relevant HTTP status code and set the body to a JSON object of the
following form:

```json
{
"type": "MachineReadable",
"message": "human readable"
}
Comment on lines +28 to +31

@chenbh chenbh May 10, 2021

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I like the jsonAPI idea of enclosing this inside a top level errors field, makes it more obvious it's an error if I forgot to look at the status code

{
  "errors": [
    {
      "type": ...
    }
  ]
}

```

If further arbitrary details are required any number of extra keys can be added
to the JSON object.
Comment on lines +34 to +35

@chenbh chenbh May 10, 2021

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What do you think of generating an UUID on 5xx errors? It could make errors a lot easier to track down in the logs



# Open Questions

* What format should we use? e.g. There's the [jsonAPI spec](https://jsonapi.org/format/#errors)

# Answered Questions



# New Implications

Allows for more flexible client-side error handling and more meaningful error
messages.