freeCodeCamp: Standardize error + flash responses

Currently the api-server sends errors messages back to the client in at least two ways. Either as a JSON response or as a query param. The former take the following shape:

{
  "message": "flash.updated-preferences",
  "type": "success",
  "variables": { "are": "optional" }
}

The query params are

{
  "messages": [ // elements have above shape ]
}

however, Fastify’s default error responses are like this:

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "body/profileUI must have required property 'isLocked'"
}

which is useful for debugging purposes.

However, we cannot send both JSON responses simultaneously. Also, we cannot merge the two, since we’d either lose the user friendly message (flash) or the detailed error message.

Issues to resolve

What do we want long term? Some combined object? For example:

{
  "statusCode": 400,
  "error": "Bad Request",
  "errorMessage": "body/profileUI must have required property 'isLocked'",
  "message": "flash.updated-preferences",
  "type": "success",
  "variables": { "are": "optional" }
}

What do we want to do in the interim? Defer fixing this until after the first release? Respond with the flash message data for now?

About this issue

Original URL
State: open
Created a year ago
Comments: 21 (20 by maintainers)

Most upvoted comments

I agree that, ideally, the client should handle what is displayed based on the response. The client should know what the user was attempting to do - i.e. Click “Save Privacy Settings” -> error -> display “Something went wrong trying to save your privacy settings”

I think this would simplify the API. We should bring it up in the next meeting. I wonder if there’s any messages that the server really does need to be in charge of. I can’t think of any, but maybe… yea, I got nothin.

moT01 on Apr 28, 2023

It might be nice to have a createResponse(code, message) function we had to use everywhere.

function createResponse(code: number, message?: string): ReplyObject {
  // Attach code, use message or default
  return { ... };
}

After thinking about it, the flash system seems like something that should be entirely handled (logicked) on the client’s side. The client should deal with defaults, and what kind of flash to show based on the error code and/or response message.

ShaunSHamilton on Apr 25, 2023

This feels post-mvp. Moved it to there, let me know if I shouldn’t have.

moT01 on Apr 30, 2024

(I don’t have enough context of the topic, but wanted to chime in anyway 😄)

I think moving the display to the client side is also easier for localization as error/success messages would need to be translated as well.

Though with statusCode and error alone, I don’t think the client would be able to map to a user-friendly message, so we would still need errorMessage for additional information. Or if it’s possible, maybe we could replace errorMessage with an errorReason property instead, which could be an enum and used in other operations on the server side.

huyenltnguyen on May 1, 2023