Return proper error codes

Return proper error codes

in API Development

Posted by: Fror.2163

Fror.2163

Hi,

I tried calling the following url: https://api.guildwars2.com/v1/wvw/match_details.json?match_id=1 I received an error 500.

Since the match with id 1 doesn’t exist either, you should return an error 404, telling me that I made a mistake, not that you made an error while searching for the erroneous input I gave.

Frór (yes, with the accent!)

Return proper error codes

in API Development

Posted by: Ruhrpottpatriot.7293

Ruhrpottpatriot.7293

Thumbs up for this.

Administrator of GW2.NET: GitHub , Forum , NuGet

Return proper error codes

in API Development

Posted by: The Talcmaster.7391

The Talcmaster.7391

It wouldn’t be a 404, because that would mean the page match_details.json doesn’t exist. A 400 (which some of them already use) would be a better choice, since that usually means a syntax error. Since we’re on the subject of error codes, a 429 (Too Many Requests) would probably be a good idea if they ever feel the need to impose a rate limit on any part of the API

Fort Aspenwood – [fury], [SAO], [NICE]
Fun on someone else’s schedule is not fun

Return proper error codes

in API Development

Posted by: Fror.2163

Fror.2163

The Talcmaster, you are wrong. 404 means that the resource cannot be found. This is typically a case where a resource cannot be found. See http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.5

Frór (yes, with the accent!)

Return proper error codes

in API Development

Posted by: AlSquire.9203

AlSquire.9203

404 seems a good choice to me, but it made me wonder if this is more relevant to an URI without a querystring (something like https://api.guildwars2.com/v1/wvw/match_details/1.json )

Seems not, as it is discussed here : http://stackoverflow.com/questions/3821663/querystring-in-rest-resource-url

Also I found this site which discuss REST API creation and different status codes. Can be useful.

Return proper error codes

in API Development

Posted by: Fror.2163

Fror.2163

All the resources you show somehow use REST. This API doesn’t provide REST. So Anet is free to use the query string part.

The 404 is valid for a query string part since the HTTP protocol doesn’t say anything about that.

Frór (yes, with the accent!)

Return proper error codes

in API Development

Posted by: The Talcmaster.7391

The Talcmaster.7391

Thank you for the technical correction on the definition of a 404, Fror. Nonetheless, it doesn’t change the appropriateness of it as the error code to return. I would say that if we were using a myriad slashes to locate something (as AlSquire pointed out) that it would be more appropriate to use a 404. Since we are passing parameters, I would say it makes more sense to use something else if a parameter is invalid.

Fort Aspenwood – [fury], [SAO], [NICE]
Fun on someone else’s schedule is not fun

Return proper error codes

in API Development

Posted by: AlSquire.9203

AlSquire.9203

I was implying that the stackoverflow thread (especially the most voted answer) convince me that 404 is appropriate even with the id part in a querystring. But ultimately it’s an API design choice.

(I’m used to the /stuff/id pattern so ?xxx_id=123 feels a little weird to me ^^)

Return proper error codes

in API Development

Posted by: Cliff Spradlin.3512

Cliff Spradlin.3512

Lead Programmer

Next

Having errors map to more specific HTTP status code is a good idea, but the reality is that we have many more complex error codes than we can map to HTTP statuses, and the errors may originate from backend servers that have no knowledge of HTTP.

Generally the way error handling should work is this:


result = get(/v1/events.json?event=123);
if (result != 200) {
    error = parseJson(resultBody);
    if (error)
        showErrorToUser(error);
    return;
}

Our error handling policy is to try to show the original error information to the user instead of hiding it. If a user reports a bug and includes the error code, there’s a good chance that we will be able to figure out the problem.

In other words, if you have a web server that talks to our API and returns results to a web browser, and you receive an error from us, try to send that error to the browser instead of swallowing it and generating your own error.

OK, on a separate topic this thread made me realize that error 500 was a bad choice. I propose changing the APIs to return error 400 instead.

Return proper error codes

in API Development

Posted by: AlSquire.9203

AlSquire.9203

Sure, a 4xx is expected because it is client side error, and 400 fits with the error description “invalid match_id”, no objection.

Or maybe 418 is better… dunno.

Return proper error codes

in API Development

Posted by: zwei.9073

zwei.9073

Having errors map to more specific HTTP status code is a good idea, but the reality is that we have many more complex error codes than we can map to HTTP statuses, and the errors may originate from backend servers that have no knowledge of HTTP.

You can only have fairly generic mapper and still give full error report in body of document, just like you do with code 500

In other words, if you have a web server that talks to our API and returns results to a web browser, and you receive an error from us, try to send that error to the browser instead of swallowing it and generating your own error.

I think that “item not found” should not be considered error.

Or rather, it is error in use of API by third party rather than error in service and as such is not error message, but info message for them.

Of course, it is often difficult to determine which is which.

Return proper error codes

in API Development

Posted by: Stefan Larimore.6872

Previous

Stefan Larimore.6872

Programmer

Next

Hi There,

I’d like to address this 500 error problem a bit:

My proposal is to only return 500 on a relatively small set of known internal errors. Otherwise, I assume it is user error and return 400. I thought about trying to map to more granular HTTP errors, but as Cliff posted above it is a difficult and un-maintainable job.

With my proposed fix, it is still possible that I missed a few “internal” errors which will come back as 400. But as before, the error details will be provided in both 400 and 500 cases. I can always add more errors to the “internal” set as needed. In general, there are many more “user-error” than “internal-error” type codes in our system.

When authenticated APIs come out, I will likely introduce the 401 error code as well.

Any thoughts on this?

Return proper error codes

in API Development

Posted by: Lil Puppy.5216

Lil Puppy.5216

If I request an id that doesn’t exist, that is the designers problem for deleting items and not using the ID again; but since it doesn’t exist, a 404 is expected on my front end so I can tell the user that item doesn’t exist.

If there is actually an internal error on the server I expect a 5xx.

All other errors are my fault and should be 4xx and I don’t particularly care which one since I’m only checking for the first number of the error code (4).
In all those cases and timeouts, the user doesn’t get to see anything and ultimately it is my problem for not getting the data properly.

It is nice to get 5xx so I can tell the user that the service is currently down or the more friendly: “We are experiencing high demand at the moment, please check back in a few minutes”.

A non 404 4xx probably means I screwed up and I’ll try one more time to get the data just in case it wasn’t me. A second fail without a 404 and I tell the user “Please check your spelling…”

I only really care about 200, 404, and 500. Anything else is extraneous programming on both our parts. If an error happened, toss me some more detailed info and we’re both happy The number of the error doesn’t do me much good but the detail info does both of us good.

Return proper error codes

in API Development

Posted by: smiley.1438

smiley.1438

I don’t usually quote myself but i think it fits this topic:

The 500 error which is thrown on any API error is somewhat misleading anyway. No matter if it’s a user error like wrong or missing params (could possibly end up in a 416), items not found (maybe a 416 as well, a 404 would be inappropirate) or “real” server errors (which are actually 500).

https://forum-en.gw2archive.eu/forum/community/api/Bug-in-Items-api/2622811

Return proper error codes

in API Development

Posted by: Dr Ishmael.9685

Dr Ishmael.9685

I don’t really understand why HTTP errors are being returned at all, except for explicit 5xx server errors and 404 errors for non-existent endpoints (e.g. /v1/character_data.json). (And 401 for authentication issues on OAuth2-enabled endpoints.) As I see it, an API error is not an HTTP error – the endpoint was reached successfully, so the HTTP status should always be 200. If the client supplied misspelled parameter names or invalid parameter values, those errors should be returned in the JSON content, not as an HTTP error code.

It seems like this would simplify things a bit. At the HTTP level, the client only needs to worry about handling 5xx and 404 error codes, which indicate that no response can be returned at all. Any other valid request should return HTTP 200, in which case the client should then check the JSON content to see if an API error was returned.

Return proper error codes

in API Development

Posted by: Stefan Larimore.6872

Previous

Stefan Larimore.6872

Programmer

Thanks for the feedback guys.

Dr. Ishmael, your argument is interesting: just return 200, 404, and 5XX and let the caller parse the results for details.

However, I do think keeping 200 for truly ‘success’ cases makes sense because internally we have one-and-only-one ‘success’ code used across the gw2. So this will always translate correctly and it doesn’t prevent anyone who wants to treat 4XX and 200 the same, relying instead on parsing the JSON for errors.