Message enum in the agency spec, error handling in the provider spec

[cttengsfmta]

All the endpoints in the agency spec return a "message enum". The definition of this enum seems to suggest that the API returns an HTTP response with no body, and a status line with a particular status code and reason phrase. Some of these response codes and reason phrases are non-standard. All 3xx response codes are for redirect responses, for instance. Also, some of the 2xx response phrases are non-standard. Response code 204 with phrase "No Content" is typically used for tracking cookie (sometimes called "pixel") requests, for example. See for reference:
https://www.w3.org/Protocols/rfc2616/rfc2616-sec6.html

The provider specification does not define behavior if an incorrect request is made.

We propose requiring a response with status code 400 and response phrase "Bad Request" for all requests to either API that cannot be processed. We further propose that all error responses have an HTTP message body required to be valid JSON with the following structure

Field Name	Type	Required	Defines
errors	Array	Yes	A list of strings. Must contain at least one error message
-	String	Yes	Informative error message

Example:

{
  "errors": [
    "inconsistent coordinates specified",
    "end_time happens before start_time!"
  ]
}

We feel that reporting all the problems present in a particular request all at once makes it easier to troubleshoot integration problems.

[hunterowens]

@cttengsfmta This is a solid proposal for handling errors. I wonder if we want an error enum to supplement the string to allow for better categorization and standardization.

[cttengsfmta]

Problem is that it's hard to imagine all possible errors that could happen. We could specify some standard ones, but leave it open to implementors to add others as needed

[hunterowens]

Agreed. I'm in the mind of "all errors have a error_catagory (enum) but the string itself can be defined by the implementor". Similar to the way python has error codes and then the error message

[cttengsfmta]

Ah, I see what you mean now. So something like

{
  "errors": [
      { "category": "geo-error-enum-value",
      "message": "inconsistent coordinates specified"
      },
      {"category": "time-error-enum-value",
      "message": "end_time happens before start_time!"
      }
  ]
}

Sounds reasonable

[lionel-panhaleux]

Hi @hunterowens , @cttengsfmta I proposed PR
#156 to address this issue.

Comments and insights are welcome ;-)