[API Request] Simpler Error Messages

by **Esfalsa** » Mon Dec 05, 2022 1:26 pm

The API currently returns errors with an HTML response that looks something like this:

Code: Select all: <!DOCTYPE html> <h1 style="color:red">Bad Request</h1> <p>Sorry, I don't know what you're asking for. <p style="font-size:small">Error: 400 Bad Request <p><a href="/pages/api.html">The NationStates API Documentation</a>

I've found this format a bit difficult to work with. Some XML parsers can't handle this data (mainly due to the lack of closing </p> tags or a root node). That leaves a few options, like bringing in an HTML parser, parsing out the error message with regex, or guessing the error based on the status code, but those all feel a bit clunky or ambiguous to me. Given that the API returns data in XML, I think it would also make sense to return errors in XML. Just spitballing here, but perhaps something like this?

Code: Select all: <ERROR> <MESSAGE>Bad Request</MESSAGE> <DETAILS>Sorry, I don't know what you're asking for.</DETAILS> </ERROR>

I realize this could make error responses less readable to the end user, but I think it's not that difficult to read this kind of response and I would also imagine that the vast majority of traffic to the API is from bots rather than humans.

I also realize this would not be backward-compatible, but according to the documentation, the API already may be updated without notice, and scripts can always specify an API version if necessary.

by **United Calanworie** » Mon Dec 05, 2022 1:56 pm

Personally I would like to see something similar to this. This best practices outline also suggests a timestamp and the API call that provoked the error.

by **Trotterdam** » Mon Dec 05, 2022 3:04 pm

Esfalsa wrote:I realize this could make error responses less readable to the end user, but I think it's not that difficult to read this kind of response and I would also imagine that the vast majority of traffic to the API is from bots rather than humans.

Yeah, but the majority of error handling is done by humans, as bots rarely care about finer distinctions between errors than "thing that means I should try again later", "thing that means I should abandon this query and go do something else", and "thing that means I should stop processing and ask for human assistance".

I exclusively use the HTTP status codes for automated error detection, and only attempt to read the actual text if the status code is confirmed as 200 OK. The point of the returned HTML page is to make errors human-readable (useful when you're manually testing an API query prior to putting it into your program). Even if the text response were bot-friendly XML rather than HTML, it would still be a bad idea to read it without consulting the status code first, since some errors may come from CloudFlare or other proxies without having ever reached the actual NationStates server.

The most important error code to take note of is 404, which typically means that a validly-formed request failed due to referencing a target that doesn't exist, such as attempting to retrieve data on a nation that ceased to exist (which happens regularly, so you want to be able to handle it in a sensible manner). Other errors generally either mean that your script is malfunctioning and sending bad requests (in which case it will probably do so consistently, so you'll notice it pretty quick) or that the server is suffering a temporary malfunction.

by **United Calanworie** » Mon Dec 05, 2022 3:30 pm

Trotterdam wrote:I exclusively use the HTTP status codes for automated error detection, and only attempt to read the actual text if the status code is confirmed as 200 OK. The point of the returned HTML page is to make errors human-readable (useful when you're manually testing an API query prior to putting it into your program). Even if the text response were bot-friendly XML rather than HTML, it would still be a bad idea to read it without consulting the status code first, since some errors may come from CloudFlare or other proxies without having ever reached the actual NationStates server.

Your views on the subject are interesting. Personally, I find the XML return that Esfalsa suggests to be perfectly readable as a human, and also most likely better for readability while scripting.

The most important error code to take note of is 404, which typically means that a validly-formed request failed due to referencing a target that doesn't exist, such as attempting to retrieve data on a nation that ceased to exist (which happens regularly, so you want to be able to handle it in a sensible manner). Other errors generally either mean that your script is malfunctioning and sending bad requests (in which case it will probably do so consistently, so you'll notice it pretty quick) or that the server is suffering a temporary malfunction.

I mean, I would say that 429s are also up there on the list of important codes to recognize and respond to, and personally they're more important than a 404. You need to immediately *stop* using a service when you receive a 429, read the Retry-After header, and then wait the appropriate amount of time before continuing to request. 404s can be error handled, so clearly 429 handling takes precedence.

by **Sandaoguo** » Mon Dec 05, 2022 3:33 pm

Trotterdam wrote:
Esfalsa wrote:I realize this could make error responses less readable to the end user, but I think it's not that difficult to read this kind of response and I would also imagine that the vast majority of traffic to the API is from bots rather than humans.
Yeah, but the majority of error handling is done by humans, as bots rarely care about finer distinctions between errors than "thing that means I should try again later", "thing that means I should abandon this query and go do something else", and "thing that means I should stop processing and ask for human assistance".

Error handling is done programmatically, a visual interface isn't needed at all.

Trotterdam wrote:The point of the returned HTML page is to make errors human-readable (useful when you're manually testing an API query prior to putting it into your program).

This is the point of API documentation. If you're manually entering in an API request in your browser, you should already know how to read XML output.

by **Trotterdam** » Mon Dec 05, 2022 3:46 pm

United Calanworie wrote:I mean, I would say that 429s are also up there on the list of important codes to recognize and respond to, and personally they're more important than a 404. You need to immediately *stop* using a service when you receive a 429, read the Retry-After header, and then wait the appropriate amount of time before continuing to request. 404s can be error handled, so clearly 429 handling takes precedence.

A well-written script should pace itself well enough to never receive a 429 error. If it somehow manages to get a 429 error anyway, that is definitely a "stop what you are doing and consult a human" situation, not a "quietly wait 15 minutes and then keep going like nothing happened, until the next time you get a 429 error" situation.

Also, either way, identifying a 429 error is far easier to do programatically by looking at the status code than at the body text.

by **United Calanworie** » Mon Dec 05, 2022 3:56 pm

Trotterdam wrote:
United Calanworie wrote:I mean, I would say that 429s are also up there on the list of important codes to recognize and respond to, and personally they're more important than a 404. You need to immediately *stop* using a service when you receive a 429, read the Retry-After header, and then wait the appropriate amount of time before continuing to request. 404s can be error handled, so clearly 429 handling takes precedence.
A well-written script should pace itself well enough to never receive a 429 error. If it somehow manages to get a 429 error anyway, that is definitely a "stop what you are doing and consult a human" situation, not a "quietly wait 15 minutes and then keep going like nothing happened, until the next time you get a 429 error" situation.

Also, either way, identifying a 429 error is far easier to do programatically by looking at the status code than at the body text.

Not every script is run on a personal device, not every script has the luxury of consulting a human. Lots of scripts are run on cloud VPSes where a human logs in once a month, perhaps, to run updates etc. That's why they should handle them sensibly, and that's why ensuring that they are handled properly is important. Because otherwise, the script will silently (or perhaps, not-so-silently) break and damage whatever workflow it is a part of.

Just because your personal situation allows for you to have your scripts check with you for situations like these does not mean that everyone is able to do so.

by **Esfalsa** » Mon Dec 05, 2022 6:41 pm

I genuinely don't see how an XML error response is that hard for humans to read. If someone can understand the XML data returned by an API query, why wouldn't they be able to read an error formatted in XML?

In fact, there are already plausible ways for someone to be reading raw, unformatted HTML error messages from the current API. I personally use an API development/testing platform, but it could be as simple as making a typo in a curl command or just calling print() on the response body to identify an error. Not everyone tests API queries from their browser address bar (especially if they want to be extra careful about setting an informative user agent), and people can understand the errors just fine even if they don't get a big red heading describing the error. If anything, error responses formatted as XML could even be easier to read in these cases.

Relying on HTTP status codes feels like bad practice. For instance, a 403 error could mean no user agent was set, that no authentication header(s) were set, or that the authentication header(s) sent were incorrect, and that list may grow longer in the future. If you want to know what actually caused the error, you have to parse the response body.

[API Request] Simpler Error Messages

[API Request] Simpler Error Messages

Who is online