5 ms·

APIs should be giving back specified error messages regardless as 4xx and 5xx errors can still be too generic. For example, if you're rate limited (429), a rob

APIs should be giving back specified error messages regardless as 4xx and 5xx errors can still be too generic. For example, if you're rate limited (429), a robust API will still give you back data on how many requests you've made and how many requests you're allowed to make, so you're still going to have to check the payload regardless. The combination of specific error status codes along with error messages has been redundant in my experience. Furthermore, in Axios, checking for `error.response.data` isn't terribly far from `error.response.status`, so I'm unsure of this "worst client experience" you're talking about. It's pretty intuitive for me.

beardedetim 5y ago
I don't want to introspect response bodies when I can introspect the status. If I'm given 429, I can automatically do something based on that. If I need to introspect the response body I have to say "okay, look inside Joe's api and look for key Foo. But in Sally's api, look for key Bar. And in Mike's api look for key Baz. And...." I think its objectively worse that I, as the engineer, need to handle all of them differently when they all could have returned to me 429 instead and I could write a general wrapper for that.
- shroompasta 5y ago
  I"m sorry, i'm not seeing the difference how is if error.response.status === 429 // then do something different than if error.response.data.err === 'RATE_LIMITED' // then do something Also, do you mean to tell me that you've never had to elaborate on your error messages and just sent back status codes with no body? I'm sorry but that does not sound like a robust API to me. 90% of my error responses have specified data, and I have to check the response body extremely often regardless of the status code being sent back.
  - beardedetim 5y ago
    Because your api returns it as error.response.data while Joe's api might put it in a different key while Mike might put it as a different key. If there's a way where we could say "this specific key will be this specific value in order to mean this specific scenario", I'd support that! But. Then. Isn't that the status that's I'm talking about? I never said the error message can't or shouldn't be introspected and totally agree we should send our clients as much info as we can to make it clear on what they can do to fix any errors! I just really really like being able to say "this specific field tells you, across all apis, what happened with this request" and don't see the gain in pushing that data into good luck finding out what key.
    - shroompasta 5y ago
      But you're already doing this for actual non-error responses... I'm currently dealing with an endpoint where it sends anywhere from 2-4mb worth of JSON data. Do I expect my clients to traverse every key and every deeply nested field to find what they're expecting for? Absolutely not. because there's an internally standardized way of dealing with things and that is also precisely how we also deal with errors. Now if you have an external API that faces many clients that you don't know about, then maybe there is consideration for usage of specific status codes. But even then, your api should have documentation for it.
      - sk5t 5y ago
        Sorry, it seems like you're dug in on this, but you're forcing clients to deserialize enormous object graphs just to figure out if there was a failure or not. This is "surprising" behavior. A better designed system would use the HTTP status code, status reason, and perhaps an additional header to convey important high-level information.
        shroompasta 5y ago
        clients don't deserialize json. object graphs should be just called json or response body; you shouldn't use all these unorthodox terms. a failure will be caught if a 400 was sent. This is how axios works - if you try a request, a 400 will automatically hit the catch. a better designed system would be specificity. 75-90% of the time you're most likely going to look at the error body anyways.
        sk5t 5y ago
        > clients don't deserialize json. I mean no personal offense but this is one of the most baffling and/or ignorant responses one could have imagined in this case.
        shroompasta 5y ago
        a simple architecture json data => python server => redis - json data gets serialized from json to string in the python server - python server then stores that string in redis to request from python server - string is retrieved from redis server - string is deserialized to send response as json the Web client is in Javascript JSON is native to Javascript it is already readable to the client, there is no deserializing that needs to happen.
  - chrsig 5y ago
    The difference is: - You have to parse the body to do that, which something like a proxy may not want to do - It's non-standard, so different implementations will result in different formats
  - sk5t 5y ago
    Actively abusing/not using the status code is not okay; this is something you see in "written by the intern" web APIs. Use the HTTP status code, please, and include other helpful details in the status message and entity body if appropriate.
    - shroompasta 5y ago
      No we won't. We have a standardized way of dealing with errors in which we will send 400/500 and have an error.data.err and an error.data.message in which err will give a title of the error, and the message elaborating the error in all of our errors across our APIs the reason being is we don't need our developers to memorize dozens of generic status codes, and can be extremely specific in our error.data.err in which status codes can't. It has worked for Facebook, It will work for us.

beardedetim 5y ago

I don't want to introspect response bodies when I can introspect the status. If I'm given 429, I can automatically do something based on that. If I need to introspect the response body I have to say "okay, look inside Joe's api and look for key Foo. But in Sally's api, look for key Bar. And in Mike's api look for key Baz. And...." I think its objectively worse that I, as the engineer, need to handle all of them differently when they all could have returned to me 429 instead and I could write a general wrapper for that.

shroompasta 5y ago
I"m sorry, i'm not seeing the difference how is if error.response.status === 429 // then do something different than if error.response.data.err === 'RATE_LIMITED' // then do something Also, do you mean to tell me that you've never had to elaborate on your error messages and just sent back status codes with no body? I'm sorry but that does not sound like a robust API to me. 90% of my error responses have specified data, and I have to check the response body extremely often regardless of the status code being sent back.
- beardedetim 5y ago
  Because your api returns it as error.response.data while Joe's api might put it in a different key while Mike might put it as a different key. If there's a way where we could say "this specific key will be this specific value in order to mean this specific scenario", I'd support that! But. Then. Isn't that the status that's I'm talking about? I never said the error message can't or shouldn't be introspected and totally agree we should send our clients as much info as we can to make it clear on what they can do to fix any errors! I just really really like being able to say "this specific field tells you, across all apis, what happened with this request" and don't see the gain in pushing that data into good luck finding out what key.
  - shroompasta 5y ago
    But you're already doing this for actual non-error responses... I'm currently dealing with an endpoint where it sends anywhere from 2-4mb worth of JSON data. Do I expect my clients to traverse every key and every deeply nested field to find what they're expecting for? Absolutely not. because there's an internally standardized way of dealing with things and that is also precisely how we also deal with errors. Now if you have an external API that faces many clients that you don't know about, then maybe there is consideration for usage of specific status codes. But even then, your api should have documentation for it.
    - sk5t 5y ago
      Sorry, it seems like you're dug in on this, but you're forcing clients to deserialize enormous object graphs just to figure out if there was a failure or not. This is "surprising" behavior. A better designed system would use the HTTP status code, status reason, and perhaps an additional header to convey important high-level information.
      - shroompasta 5y ago
        clients don't deserialize json. object graphs should be just called json or response body; you shouldn't use all these unorthodox terms. a failure will be caught if a 400 was sent. This is how axios works - if you try a request, a 400 will automatically hit the catch. a better designed system would be specificity. 75-90% of the time you're most likely going to look at the error body anyways.
        sk5t 5y ago
        > clients don't deserialize json. I mean no personal offense but this is one of the most baffling and/or ignorant responses one could have imagined in this case.
        shroompasta 5y ago
        a simple architecture json data => python server => redis - json data gets serialized from json to string in the python server - python server then stores that string in redis to request from python server - string is retrieved from redis server - string is deserialized to send response as json the Web client is in Javascript JSON is native to Javascript it is already readable to the client, there is no deserializing that needs to happen.
- chrsig 5y ago
  The difference is: - You have to parse the body to do that, which something like a proxy may not want to do - It's non-standard, so different implementations will result in different formats
- sk5t 5y ago
  Actively abusing/not using the status code is not okay; this is something you see in "written by the intern" web APIs. Use the HTTP status code, please, and include other helpful details in the status message and entity body if appropriate.
  - shroompasta 5y ago
    No we won't. We have a standardized way of dealing with errors in which we will send 400/500 and have an error.data.err and an error.data.message in which err will give a title of the error, and the message elaborating the error in all of our errors across our APIs the reason being is we don't need our developers to memorize dozens of generic status codes, and can be extremely specific in our error.data.err in which status codes can't. It has worked for Facebook, It will work for us.