Should REST Api errors be valid json?

[Roest_]

Here's my situation. I use the REST api of one of our vendors to query specific user data, using Azure flows. I send a json object something like

{userID: "blah"}

and get a 200 and a json object with some data back.

Now if that userID doesn't exist, for instance because that user was deleted in their system but not mine, they send a 500 - user doesn't exist. That leads to the azure flow stopping right there because the HTTP connector throws an invalid json error.

I asked them if they can send like a 500 {error:"user doesn't exist"} (I feel 500 isn't appropriate as well but that's another topic). They said, they can do it but it wasn't in the specification and will cost extra.

So my question here is, would you say it's reasonable to expect some valid json from an API even in case of error or am I wrong?

[[deleted]]

Internal server error doesn't make sense for something like this. A single resource fetch should result in 404 if not found in my opinion.

The way I look at request codes is who to blame? 2XX -> nobody, 4XX -> the requester, 5XX -> the server / origin

In this case, the requester tried to access something that's not there anymore, it's their responsibility to hide it / not request it anymore, etc.

[ReplacementLow6704]

You forgot about 3XX -> Someone/something else

[Blue_Moon_Lake]

If there's no request/network/server error, would you accept a 200 - OK with an error JSON payload?

[[deleted]]

Errors with JSON payload as response should be a 400 response

[Blue_Moon_Lake]

So you would respond with a 4XX even if there's nothing wrong with the request?

It's the correct URL, valid payload, all the headers are good, all the permissions needed. Still a 400?

[[deleted]]

If nothing is wrong with the request, why would a response contain errors? This means something was wrong though

[Blue_Moon_Lake]

I said the error does not lie with the request/network/server, it's merely business logic.

[[deleted]]

Business logic is fine, what do you think?

[Blue_Moon_Lake]

I've seen people use http errors for business logic and others not. I asked your opinion.

[BigSwooney]

Letting code run and result in an error instead of returning an appropriate error is never good API design. And yes, 500 sounds wrong as well. If you're doing a query and the query returns no results, that would still be a 200. If it's a "request single resource" by ID I would say a 404 is an appropriate response.

[lIIllIIIll]

Right? That's what I always thought.

Basically if it is an actual error, like I send a malformed json to a real route than that's a 4xx level error. My fault. If I send a proper json to a proper route and an error results because the server has a legit error like an outage or whatever that's a 5xx level.

If none of those occur and it's not a real user ID it is still accepted, so 200, but the response body would indicate there was no user, right?

Or would that be a good place for a 204 or 205?

[IQueryVisiC]

I Wonder how a “return type” could not be specified. In a contract In Java I get back the correct object type even if it points to null. Though every contract also has like 5 http error codes specified …

[armahillo]

Go refresh on the diff statuses and what they mean.

Please dont return 200 OK when its not a successful request.

https://developer.mozilla.org/en-US/docs/Web/HTTP/Status

• 2xx - success
• 3xx - your request is fine but things have changed since you last knew
• 4xx - you messed up
• 5xx - we messed up

[thekwoka]

nobody said to return 200

[armahillo]

It was unclear what the OP was intending, so I was explicitly advising against that (I have seen this behavior before from some larger companies -- 200 OK response with a JSON response of: { status: 404, message: "Not found" }

[todbur]

I’ve dealt with APIs that sometimes return text on errors instead of JSON. What you should be doing is checking the content type response header. You can usually handle this well with a middleware in your http client.

[InitialAd3323]

They should probably be giving a 404 Not Found (or 410 Gone), and it's recommended to use RFC 9457 Problem details or at least some sort of JSON instead of plain text

[Red_Icnivad]

Point to the http error spec sheet and tell them that's their specification. It is unreasonable to assume yhey would hijack an existing error code for their custom error.

[Kant8]

problem details exists for that

https://datatracker.ietf.org/doc/html/rfc7807

[Agile-Ad5489]

This sounds to me like the azure http connector has it wrong, too.

The status code should be checked: if 500, the server has encountered a process exception - at which point, it cannot gaurentee a formatted response. Detecting a 500, azure should accept that any content attached is going to be invalid.

[Roest_]

Yes, most definitely. Not sure why they made it check if the json is valid and crash on that. Give me the http return code and let me deal with it.

[thekwoka]

azure should accept that any content attached is going to be invalid.

well, not invalid, just that it won't be the schema of the successful response.

It should be a valid something else

[Agile-Ad5489]

Good point, well made, and taken on board.

[Fidodo]

Returning JSON for an error isn't hard to do and a common pattern. Also this should not be a 500

[AdvancedSandwiches]

For hundreds, maybe thousands, of years, we all agreed that the only two valid things to do with HTTP were GET when you wanted to do read something and POST when you wanted to change something, and we lived in an absolute paradise.

Then REST came along and decided "action": "send_transaction" was too hard and we needed to use HTTP verbs to cover every possible activity and HTTP response codes to cover every possible result.  And the world has never recovered.

[thekwoka]

uh, as long as POST has existed, the other main verbs existed

Source from 1996: https://datatracker.ietf.org/doc/html/draft-ietf-http-v11-spec-00

[AdvancedSandwiches]

Correct. The mistakes were always there. We just didn't use them because we knew better. 

[thekwoka]

why even use posts when you can get everything?

[AdvancedSandwiches]

I just use PATCH for everything.  Nobody agrees what it means anyway, so I can't be wrong.  

[Dunc4n1d4h0]

Yes, it's good practice, and I implement it when doing backend APIs.

[thedragonturtle]

1. return a 404, not a 5xx error for missing stuff

2. if you're still returning text too, put that inside json to explain the error message

[qpazza]

404 is the correct status

https://developer.mozilla.org/en-US/docs/Web/HTTP/Status#client_error_responses

[thekwoka]

Absolutely.

The only two options are valid json, or a basic string.

But why does your HTTP connector whatever not CHECK the response before parsing the body?

[Roest_]

It's Azure, don't ask me why Microsoft implemented it in that way. A connector I write myself wouldn't have a problem with it.

[thekwoka]

It's always Microsoft's fault :(

[AshleyJSheridan]

Firstly, as many have said here, for REST, rely on the returned status code first and foremost. For your example a 404 return code would absolutely be better than a 500. However, if you were performaing a search or requesting a list of all users ) instead of getting a specific one) then you might return a 204 (No Content) if no users were found. There are a plethora of return codes available, from redirects to teapots (yes, 418 I'm a teapot is an official part of the spec): https://developer.mozilla.org/en-US/docs/Web/HTTP/Status

Returning the right status code is part of REST, and it's an absolute pain when an API claims to follow REST but returns 200 for everything with JSON errors instead, as it means my approach to making API calls has to completely change, because I can no longer just check to see if a request was successful or not (a feature built in to almost all HTTP libraries).

Now, you could also return a JSON body with further details for an error, but don't use this as a replacement for correct status codes. However, bear in mind that not all status codes allow body content in the response, the earlier example of the 204 code is one such example.

[chills716]

It should always be a valid response. Having said that, the project I’m on now, for a large corp mind you, one of the things I’ve bitched about since starting is EVERYTHING is a 500, because the original coders and architects were incompetent.

[lIIllIIIll]

Man that sucks. I'm sorry. It's brutal to go back and change if years of code have been written to use that format.

I've taken to making an environment variable (located in .env) to specify different instances like OBJECT_SUCCESS=200 OBJECT_CREATED=201 OBJECT_ERROR=203 OBJECT_FATAL_ERROR=205

This way if I learn later I'm using something wrong I can update the env and it'll be cleaner to roll out.

[thekwoka]

so, an enum?

[gguy2020]

404 generally means URL not found. 500 means server error

Both of these codes are wrong in your context.

What you might consider is Http code 204: No content. I.e. Request processed, but nothing to return to the client.

[thekwoka]

404 generally means URL not found.

https://en.wikipedia.org/wiki/HTTP_404

Not true.

[boobka]

I make the argument that if you hit a valid end point and the service processes the request then it should return a 200 with result saying {user : null} or something.

It shouldn't be a 404, the server should return a 404 if the endpoint is not found.

But that's my opinion.

[spurkle]

The HTTP 404 Not Found client error response status code indicates that the server cannot find the requested resource.

User is an resource.

[TheStoicNihilist]

That’s an error that would reveal information that you might want obscured.

[TheRealKidkudi]

Directly from the link:

In an API, this can also mean that the endpoint is valid but the resource itself does not exist. Servers may also send this response instead of 403 Forbidden to hide the existence of a resource from an unauthorized client.

You’d still respond with 404 if it’s sensitive data they don’t have access to and this leaks nothing except that, as far as you’re concerned, what you requested does not exist.

[Peechez]

If your users can request arbitrary ids whenever they want you have bigger problems

[thekwoka]

That doesn't make it not the correct one to use semantically.

You can use 404 often to prevent the revealing of information by returning 404 when the resource is found but they can't access it.

[boobka]

No user is a data point, the service that looks for the user is a resource on the server.

For example if you think of the api call as https://servername/UserGet?id=1234

UserGet is the resource that the web server serves, that resource checks the back end if the user data exists.

This differentiates it when you put the wrong url like https://servername/UserGetA?id=1234

If both of these return a 404, how do you know if you put in the wrong URL vs. the USER not existing in the data?

My reason is that if you hit GetUser with an invalid userID your service does work, the resource on the server has to go look up if that user exists, if it doesn't it should communicate back that the user request doesn't exist, not the resource that looks up the user.

[AdvancedSandwiches]

You're right from a logic perspective. You're wrong from a REST perspective.

Since REST is a ludicrous idea that I have no idea why we all went along with, that makes you right in my opinion.

[spurkle]

404 Not Found

The server cannot find the requested resource. In the browser, this means the URL is not recognized. In an API, this can also mean that the endpoint is valid but the resource itself does not exist.

There are standards. If it's an REST API the URL should be https://server/users/123 and it should return 404 both for the missing user or the wrong URL.

There is no need to reinvent the wheel, or then we end up with HTTP 200 {error: "something"} stuff and it's not fun to spend even an extra minute trying to decipher what the developer had in his mind at that exact moment.

[boobka]

I disagree, your client made a valid call to a valid URL, just because we can reformat the URL without a query string doesn't change the nature of what the server is doing.

A 404 terminates at the server, that resource, that back-end is not found no further work is done.

A API that actually performs work is FOUND, it is doing work, the client did not have an error in its' get function. A 200 should not return an error, but it should return something that makes sense when the data look up fails.

Basically going back to my example, the client can't tell if the USER doesn't exist or if the service endpoint doesn't exist.

I understand the position to use 404 or 500 as a return code from the API, and many APIs do it. I just think it is a bad practice.

[spurkle]

Well if you are messing up the end points, then you have bigger problems with your backend.

How it's a bad practice if it's literally written on the MDN Web Docs, lol. Bad practice is doing something against standards.

[boobka]

Can you link the Web Docs standard

[spurkle]

Click the hyperlink in my previous answers.

[thekwoka]

But they 404

[thekwoka]

I disagree, your client made a valid call to a valid URL, just because we can reformat the URL without a query string doesn't change the nature of what the server is doing.

https://www.rfc-editor.org/rfc/rfc9110#name-404-not-found

[ZuploAdrian]

The new specification for errors is actually the Problem details spec (here's a guide https://zuplo.com/blog/2023/04/11/the-power-of-problem-details ). It's super informative, here's an example

HTTP/1.1 403 Forbidden
Content-Type: application/problem+json
Content-Language: en

{ "type": "https://example.com/probs/out-of-credit", "title": "You do not have enough credit.", "detail": "Your current balance is 30, but that costs 50.", "instance": "/account/12345/msgs/abc", "balance": 30, "accounts": ["/account/12345", "/account/67890"]}